RubyGems - unisender-ruby - Versions diffs - 0.1.1 → 0.2.0 - Mend

unisender-ruby 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +89 -0
data/CONTRIBUTING.md +10 -1
data/README.md +55 -112
data/docs/api.md +395 -210
data/docs/execution.md +89 -0
data/docs/import-recovery.md +41 -0
data/docs/live-contracts.md +34 -0
data/docs/migration-0.2.md +129 -0
data/docs/rails.md +248 -0
data/docs/releases.md +4 -4
data/docs/testing.md +83 -0
data/docs/usage.md +144 -0
data/docs/webhooks.md +41 -0
data/examples/campaign.rb +5 -6
data/examples/campaign_lifecycle.rb +28 -0
data/examples/check_connection.rb +1 -1
data/examples/events.rb +1 -1
data/examples/export.rb +20 -6
data/examples/import.rb +3 -2
data/examples/import_recovery.rb +70 -0
data/examples/quickstart.rb +1 -1
data/examples/subscribe.rb +2 -2
data/lib/unisender/acceptance.rb +104 -0
data/lib/unisender/attachment.rb +47 -0
data/lib/unisender/batch_report.rb +115 -0
data/lib/unisender/batch_summary.rb +87 -0
data/lib/unisender/batches.rb +41 -12
data/lib/unisender/campaign_workflow.rb +72 -0
data/lib/unisender/client.rb +65 -33
data/lib/unisender/client_configuration.rb +50 -0
data/lib/unisender/client_execution.rb +43 -0
data/lib/unisender/client_state.rb +31 -0
data/lib/unisender/client_validation.rb +97 -0
data/lib/unisender/configuration.rb +151 -0
data/lib/unisender/contact_records.rb +251 -0
data/lib/unisender/diagnostic_urls.rb +68 -0
data/lib/unisender/diagnostics.rb +83 -0
data/lib/unisender/download_target.rb +61 -0
data/lib/unisender/download_transfer.rb +43 -0
data/lib/unisender/downloader.rb +99 -0
data/lib/unisender/error_diagnostics.rb +83 -0
data/lib/unisender/errors.rb +125 -8
data/lib/unisender/event_batches.rb +40 -0
data/lib/unisender/event_payload.rb +50 -22
data/lib/unisender/events.rb +21 -5
data/lib/unisender/execution_context.rb +114 -0
data/lib/unisender/form.rb +20 -12
data/lib/unisender/helpers.rb +70 -10
data/lib/unisender/hooks.rb +79 -0
data/lib/unisender/import_cells.rb +62 -0
data/lib/unisender/input_types.rb +30 -0
data/lib/unisender/inputs.rb +262 -0
data/lib/unisender/iteration.rb +15 -0
data/lib/unisender/iterators.rb +60 -0
data/lib/unisender/mail_inputs.rb +37 -0
data/lib/unisender/named_inputs.rb +52 -0
data/lib/unisender/observation.rb +30 -0
data/lib/unisender/operation_contracts.rb +106 -0
data/lib/unisender/operations/contacts_1.rb +4 -3
data/lib/unisender/operations/contacts_2.rb +23 -4
data/lib/unisender/operations/messages_1.rb +7 -4
data/lib/unisender/operations/messages_2.rb +8 -3
data/lib/unisender/operations/messages_3.rb +1 -1
data/lib/unisender/operations/notes_1.rb +1 -1
data/lib/unisender/operations/statistics_1.rb +3 -3
data/lib/unisender/operations/templates_1.rb +2 -2
data/lib/unisender/outcomes.rb +320 -0
data/lib/unisender/page_response.rb +48 -0
data/lib/unisender/paginated_operations.rb +43 -2
data/lib/unisender/pagination.rb +53 -20
data/lib/unisender/persistent_transport.rb +104 -0
data/lib/unisender/rate_limiter.rb +72 -0
data/lib/unisender/record.rb +210 -0
data/lib/unisender/record_rows.rb +69 -0
data/lib/unisender/records.rb +614 -0
data/lib/unisender/request_execution.rb +108 -0
data/lib/unisender/response.rb +13 -10
data/lib/unisender/result_registry.rb +72 -0
data/lib/unisender/results.rb +105 -0
data/lib/unisender/retry_policy.rb +10 -16
data/lib/unisender/serialization.rb +54 -0
data/lib/unisender/statistic_records.rb +129 -0
data/lib/unisender/task_response.rb +85 -0
data/lib/unisender/task_waiter.rb +25 -11
data/lib/unisender/testing/assertions.rb +48 -0
data/lib/unisender/testing/fixtures.rb +24 -0
data/lib/unisender/testing.rb +91 -0
data/lib/unisender/transport.rb +17 -9
data/lib/unisender/validation.rb +11 -9
data/lib/unisender/version.rb +1 -1
data/lib/unisender/webhooks/tokens.rb +38 -0
data/lib/unisender/webhooks.rb +230 -0
data/lib/unisender.rb +42 -0
data/sig/acceptance.rbs +30 -0
data/sig/attachment.rbs +15 -0
data/sig/batch_summary.rbs +38 -0
data/sig/campaign_workflow.rbs +20 -0
data/sig/configuration.rbs +62 -0
data/sig/connection_controls.rbs +55 -0
data/sig/diagnostics.rbs +37 -0
data/sig/domain_records.rbs +96 -0
data/sig/downloads.rbs +53 -0
data/sig/execution.rbs +52 -0
data/sig/execution_context.rbs +46 -0
data/sig/hooks.rbs +18 -0
data/sig/inputs.rbs +84 -0
data/sig/iterators.rbs +11 -0
data/sig/mail_inputs.rbs +8 -0
data/sig/manifest.yaml +11 -0
data/sig/operation_contracts.rbs +28 -0
data/sig/operations.rbs +73 -69
data/sig/outcomes.rbs +90 -0
data/sig/record.rbs +77 -0
data/sig/records.rbs +182 -0
data/sig/serialization.rbs +13 -0
data/sig/tasks.rbs +26 -0
data/sig/testing.rbs +54 -0
data/sig/unisender.rbs +128 -39
data/sig/webhooks.rbs +55 -0
metadata +84 -3

data/docs/api.md CHANGED Viewed

@@ -2,72 +2,143 @@
 Contract audit: 2026-10-25. The [official UniSender documentation](https://www.unisender.com/ru/support/category/api/) is the source of truth. Tests use deterministic, artificial responses and do not establish live account compatibility.
-All methods return `Unisender::Response`; named operations declare their result type as `Response[Result]`. Required arguments are Ruby keywords. Optional keywords default to omission, preserving the service's defaults. RBS signatures ship with the gem. Identifiers accept integers or strings; flags accept booleans or 0/1. Dates remain strings in the format and time zone documented for each method.
+Named HTTP operations return typed `Unisender::Response` subclasses. Required arguments are Ruby keywords. Optional keywords normally default to omission; documented client defaults take precedence. RBS signatures ship with the gem. Identifiers accept integers or strings; flags accept booleans or 0/1. Timestamp arguments accept strings or Ruby `Time` values. Time values use the method's documented UTC format.
 Arrays supplied to comma-separated fields are joined only by named methods. For other array or hash arguments, the form encoder emits explicit bracket indices. `request(method, params: {})` accepts the exact wire method and parameters; it does not perform method-specific conversions or validation.
+## Choose an operation
+| Task | Starting point |
+| --- | --- |
+| Iterate lists | `get_lists.each` |
+| Iterate every message or campaign | `each_message`, `each_message_summary`, or `each_campaign` |
+| Manage a subscription | `subscribe(email:, list_ids:)` |
+| Import application records | `import_contacts_in_batches(records:)` |
+| Export contacts | `export_contacts(...).wait` |
+| Inspect acceptance | `complete?`, `partial?`, `uncertain?`, and `failures` on report responses |
+| Test without networking | [Testing transport](testing.md) |
+| Configure an application | [Rails integration and configuration](rails.md) |
+Named reads make one request. A fetched page's `each` remains local.
+`each_page`, `auto_each`, and named iterators explicitly traverse further pages.
+Batch commands execute immediately. Their `each_*` equivalents accept a block or return a lazy Enumerator.
+### Effects and recovery
+| Interface | Work performed | Recovery rule |
+| --- | --- | --- |
+| `validate!`, record readers, serializers | Local only | Correct the reported input path. |
+| Named reads | One HTTP request | Opt-in retries cover only the explicit read allowlist. |
+| `each_*`, `each_page`, `auto_each` | Requests as consumed | Save `next_offset` after processing; repeated enumeration starts another sequence. |
+| `subscribe`, create/update/delete operations | Account mutation | Reconcile an uncertain result before repeating. |
+| `send_email`, `send_sms`, `send_test_email` | Sends messages | Acceptance does not prove delivery; never automatically replay. |
+| `create_campaign`, `send_campaign` | Schedules or starts a send | Save the returned campaign ID and observe that same campaign. |
+| Imports and Event Tracking | Mutations, possibly partial | Keep source IDs and checkpoints; [reconcile failed ranges](import-recovery.md). |
+| `export_contacts`, report tasks | Starts a remote job | Save `task_uuid`; resume it with `get_task_result`. |
+| `wait`, `download_to` | Explicit polling or download | Terminal waits are local; downloads retain confirmed partial bytes on failure. |
+### Identifier map
+| Identifier | Obtain from | Pass to |
+| --- | --- | --- |
+| List ID | `get_lists` record `id`, `create_list.id` | `list_id:` or `list_ids:` |
+| Message ID | `create_email_message.message_id`, message record `id` | `get_message(id:)`, `send_test_email(id:)`, `create_campaign(message_id:)` |
+| Campaign ID | `create_campaign.campaign_id` | `get_campaign_status(campaign_id:)`, campaign statistics |
+| Accepted direct-email ID | `send_email.accepted_ids` | `check_email(email_id:)` |
+| SMS ID | `send_sms` receipt `sms_id` | `check_sms(sms_id:)` |
+| Template ID | Template record `id` | `get_template(template_id:)`, template update/delete |
+| Task UUID | `export_contacts.task_uuid`, report task | `get_task_result(task_uuid:)` |
+| Field, tag, or note ID | Corresponding record `id` | The operation's explicit `id:` or `field_ids:` keyword |
+Identifiers refer to different resources even when their values happen to match.
+`get_messages` returns detailed message records. `list_messages` returns message summaries.
+Both fetch one page; use `each_message` or `each_message_summary` for explicit traversal.
+### Common Ruby calls
+Use these calls with an application-owned `client`. Mutations below change an account or send messages.
+```ruby
+client.get_lists.map(&:title)
+client.get_contact(email: "person@example.test").email_address
+client.validate!(:subscribe, email: "person@example.test", list_ids: [42])
+client.subscribe(email: "person@example.test", list_ids: [42]) # Sends confirmation by default.
+client.import_contacts(records: [{ email: "person@example.test" }]).complete?
+client.send_sms(phone: ["79000000000"], sender: "Shop", text: "Hello").map(&:sms_id)
+client.get_message(id: 12).subject
+client.get_campaign_status(campaign_id: 34).status
+client.get_task_result(task_uuid: "saved-task").wait
+```
+See the executable [campaign lifecycle](../examples/campaign_lifecycle.rb), [import recovery](import-recovery.md), and [export](../examples/export.rb) examples for multi-step workflows.
+Object responses forward result readers and Hash-style lookups. Collections yield records and expose Array-style access.
+Use `result` for the typed value, `data` for the raw envelope, and `http_status` for HTTP metadata.
 ## Implemented operations
 The offline contract cases are in `test/fixtures/operations.json` and run through `test/operations_test.rb` in the source checkout. Every entry verifies the path, authentication body, required arguments, a successful result, and API failure propagation.
-| Ruby method | Wire method and documentation | Required keywords | Optional keywords |
-| --- | --- | --- | --- |
-| [`create_list`](#create_list) | [`createList`](https://www.unisender.com/ru/support/api/contacts/createlist/) | `title` | `before_subscribe_url`, `after_subscribe_url`, `sub_user_rights` |
-| [`delete_list`](#delete_list) | [`deleteList`](https://www.unisender.com/ru/support/api/contacts/deletelist/) | `list_id` | None |
-| [`exclude`](#exclude) | [`exclude`](https://www.unisender.com/ru/support/api/contacts/exclude/) | `contact_type`, `contact` | `list_ids` |
-| [`export_contacts`](#export_contacts) | [`async/exportContacts`](https://www.unisender.com/ru/support/api/contacts/exportcontacts/) | None | `notify_url`, `list_id`, `field_names`, `email`, `phone`, `tag`, `email_status`, `phone_status`, `contact_status` |
-| [`get_contact_count`](#get_contact_count) | [`getContactCount`](https://www.unisender.com/ru/support/api/contacts/getcontactcount/) | `list_id`, `params` | None |
-| [`get_lists`](#get_lists) | [`getLists`](https://www.unisender.com/ru/support/api/contacts/getlists/) | None | None |
-| [`get_total_contacts_count`](#get_total_contacts_count) | [`getTotalContactsCount`](https://www.unisender.com/ru/support/api/contacts/gettotalcontactscount/) | `login` | None |
-| [`import_contacts`](#import_contacts) | [`importContacts`](https://www.unisender.com/ru/support/api/contacts/importcontacts/) | `field_names`, `data` | `overwrite_tags`, `overwrite_lists`, `telegram_bot_channel_id` |
-| [`subscribe`](#subscribe) | [`subscribe`](https://www.unisender.com/ru/support/api/contacts/subscribe/) | `list_ids`, `fields` | `tags`, `double_optin`, `overwrite` |
-| [`update_list`](#update_list) | [`updateList`](https://www.unisender.com/ru/support/api/contacts/updatelist/) | `list_id`, `title` | `before_subscribe_url`, `after_subscribe_url`, `sub_user_rights` |
-| [`is_contact_in_lists`](#is_contact_in_lists) | [`isContactInLists`](https://www.unisender.com/ru/support/api/contacts/iscontactinlists/) | `email`, `list_ids`, `condition` | None |
-| [`get_contact`](#get_contact) | [`getContact`](https://www.unisender.com/ru/support/api/contacts/getcontact/) | `email` | `include_lists`, `include_fields`, `include_details` |
-| [`unsubscribe`](#unsubscribe) | [`unsubscribe`](https://www.unisender.com/ru/support/api/contacts/unsubscribe/) | `contact_type`, `contact` | `list_ids` |
-| [`cancel_campaign`](#cancel_campaign) | [`cancelCampaign`](https://www.unisender.com/ru/support/api/messages/cancel-campaign/) | `campaign_id` | None |
-| [`check_email`](#check_email) | [`checkEmail`](https://www.unisender.com/ru/support/api/messages/check-email/) | `email_id` | None |
-| [`check_sms`](#check_sms) | [`checkSms`](https://www.unisender.com/ru/support/api/messages/check-sms/) | `sms_id` | None |
-| [`create_campaign`](#create_campaign) | [`createCampaign`](https://www.unisender.com/ru/support/api/messages/createcampaign/) | `message_id` | `start_time`, `timezone`, `track_read`, `track_links`, `contacts`, `contacts_url`, `track_ga`, `payment_limit`, `payment_currency`, `ga_medium`, `ga_source`, `ga_campaign`, `ga_content`, `ga_term` |
-| [`create_email_message`](#create_email_message) | [`createEmailMessage`](https://www.unisender.com/ru/support/api/messages/createemailmessage/) | `sender_name`, `sender_email`, `list_id` | `subject`, `body`, `text_body`, `generate_text`, `tag`, `attachments`, `lang`, `template_id`, `system_template_id`, `wrap_type`, `categories` |
-| [`create_sms_message`](#create_sms_message) | [`createSmsMessage`](https://www.unisender.com/ru/support/api/messages/createsmsmessage/) | `sender`, `body`, `list_id` | `tag` |
-| [`delete_message`](#delete_message) | [`deleteMessage`](https://www.unisender.com/ru/support/api/messages/deletemessage/) | `message_id` | None |
-| [`get_actual_message_version`](#get_actual_message_version) | [`getActualMessageVersion`](https://www.unisender.com/ru/support/api/messages/get-actual-message-version/) | `message_id` | None |
-| [`get_web_version`](#get_web_version) | [`getWebVersion`](https://www.unisender.com/ru/support/api/messages/getwebversion/) | `campaign_id` | None |
-| [`send_email`](#send_email) | [`sendEmail`](https://www.unisender.com/ru/support/api/messages/sendemail/) | `email`, `sender_name`, `sender_email`, `subject`, `body`, `list_id` | `attachments`, `lang`, `track_read`, `track_links`, `cc`, `headers`, `images_as`, `ref_key`, `error_checking`, `metadata` |
-| [`send_sms`](#send_sms) | [`sendSms`](https://www.unisender.com/ru/support/api/messages/sendsms/) | `phone`, `sender`, `text` | None |
-| [`send_test_email`](#send_test_email) | [`sendTestEmail`](https://www.unisender.com/ru/support/api/messages/sendtestemail/) | `email`, `id` | None |
-| [`update_email_message`](#update_email_message) | [`updateEmailMessage`](https://www.unisender.com/ru/support/api/messages/updateemailmessage/) | `id` | `sender_name`, `sender_email`, `subject`, `body`, `list_id`, `text_body`, `lang`, `categories` |
-| [`update_opt_in_email`](#update_opt_in_email) | [`updateOptInEmail`](https://www.unisender.com/ru/support/api/messages/updateoptinemail/) | `sender_name`, `sender_email`, `subject`, `body`, `list_id` | None |
-| [`get_sender_domain_list`](#get_sender_domain_list) | [`getSenderDomainList`](https://www.unisender.com/ru/support/api/messages/getsenderdomainlist/) | `username` | `domain`, `limit`, `offset` |
-| [`get_campaign_common_stats`](#get_campaign_common_stats) | [`getCampaignCommonStats`](https://www.unisender.com/ru/support/api/statistics/get-campaign-common-stats/) | `campaign_id` | None |
-| [`get_campaign_delivery_stats`](#get_campaign_delivery_stats) | [`async/getCampaignDeliveryStats`](https://www.unisender.com/ru/support/api/statistics/getcampaigndeliverystats/) | `campaign_id` | `notify_url`, `changed_since`, `field_ids` |
-| [`get_campaign_status`](#get_campaign_status) | [`getCampaignStatus`](https://www.unisender.com/ru/support/api/statistics/getcampaignstatus/) | `campaign_id` | None |
-| [`get_messages`](#get_messages) | [`getMessages`](https://www.unisender.com/ru/support/api/statistics/getmessages/) | `date_from`, `date_to` | `limit`, `offset` |
-| [`get_visited_links`](#get_visited_links) | [`getVisitedLinks`](https://www.unisender.com/ru/support/api/statistics/getvisitedlinks/) | `campaign_id` | `group` |
-| [`list_messages`](#list_messages) | [`listMessages`](https://www.unisender.com/ru/support/api/statistics/listmessages/) | `date_from`, `date_to` | `limit`, `offset` |
-| [`get_campaigns`](#get_campaigns) | [`getCampaigns`](https://www.unisender.com/ru/support/api/statistics/getcampaigns/) | `from` | `to`, `limit`, `offset` |
-| [`get_message`](#get_message) | [`getMessage`](https://www.unisender.com/ru/support/api/statistics/getmessage/) | `id` | None |
-| [`get_task_result`](#get_task_result) | [`async/getTaskResult`](https://www.unisender.com/ru/support/api/statistics/../contacts/exportcontacts/) | `task_uuid` | None |
-| [`create_email_template`](#create_email_template) | [`createEmailTemplate`](https://www.unisender.com/ru/support/api/templates/createemailtemplate/) | `title`, `subject`, `body` | `description`, `text_body`, `lang` |
-| [`delete_template`](#delete_template) | [`deleteTemplate`](https://www.unisender.com/ru/support/api/templates/deletetemplate/) | `template_id` | None |
-| [`get_template`](#get_template) | [`getTemplate`](https://www.unisender.com/ru/support/api/templates/gettemplate/) | None | `template_id`, `system_template_id` |
-| [`get_templates`](#get_templates) | [`getTemplates`](https://www.unisender.com/ru/support/api/templates/gettemplates/) | None | `type`, `date_from`, `date_to`, `limit`, `offset` |
-| [`list_templates`](#list_templates) | [`listTemplates`](https://www.unisender.com/ru/support/api/templates/listtemplates/) | None | `type`, `date_from`, `date_to`, `limit`, `offset` |
-| [`update_email_template`](#update_email_template) | [`updateEmailTemplate`](https://www.unisender.com/ru/support/api/templates/updateemailtemplate/) | `template_id` | `title`, `description`, `subject`, `body`, `text_body`, `lang` |
-| [`create_field`](#create_field) | [`createField`](https://www.unisender.com/ru/support/api/inputs/createfield/) | `name`, `type` | `public_name` |
-| [`delete_field`](#delete_field) | [`deleteField`](https://www.unisender.com/ru/support/api/inputs/deletefield/) | `id` | None |
-| [`delete_tag`](#delete_tag) | [`deleteTag`](https://www.unisender.com/ru/support/api/inputs/deletetag/) | `id` | None |
-| [`get_fields`](#get_fields) | [`getFields`](https://www.unisender.com/ru/support/api/inputs/getfields/) | None | None |
-| [`get_tags`](#get_tags) | [`getTags`](https://www.unisender.com/ru/support/api/inputs/gettags/) | None | None |
-| [`update_field`](#update_field) | [`updateField`](https://www.unisender.com/ru/support/api/inputs/updatefield/) | `id`, `name` | `public_name` |
-| [`get_contact_field_values`](#get_contact_field_values) | [`getContactFieldValues`](https://www.unisender.com/ru/support/api/inputs/getcontactfieldvalues/) | `email`, `field_ids` | None |
-| [`create_subscriber_note`](#create_subscriber_note) | [`createSubscriberNote`](https://www.unisender.com/ru/support/api/notes/createsubscibernote/) | `subscriber_id`, `content` | None |
-| [`update_subscriber_note`](#update_subscriber_note) | [`updateSubscriberNote`](https://www.unisender.com/ru/support/api/notes/updatesubcribernote/) | `id`, `content` | None |
-| [`delete_subscriber_note`](#delete_subscriber_note) | [`deleteSubscriberNote`](https://www.unisender.com/ru/support/api/notes/deletesubscribernote/) | `id` | None |
-| [`get_subscriber_note`](#get_subscriber_note) | [`getSubscriberNote`](https://www.unisender.com/ru/support/api/notes/getsubscribernote/) | `id` | None |
-| [`get_subscriber_notes`](#get_subscriber_notes) | [`getSubscriberNotes`](https://www.unisender.com/ru/support/api/notes/getsubscribernotes/) | `subscriber_id` | `limit`, `offset`, `order_type`, `order_by`, `is_pinned` |
-| `track_events` | [Event Tracking](https://www.unisender.com/ru/support/api/event-tracking-api/) | `events` | None |
+| Ruby method | Wire method and documentation | Required inputs | Optional keywords | Typed result |
+| --- | --- | --- | --- | --- |
+| [`create_list`](#create_list) | [`createList`](https://www.unisender.com/ru/support/api/contacts/createlist/) | `title` | `before_subscribe_url`, `after_subscribe_url`, `sub_user_rights` | `IdentifierRecordResponse` |
+| [`delete_list`](#delete_list) | [`deleteList`](https://www.unisender.com/ru/support/api/contacts/deletelist/) | `list_id` | None | `ObjectResponse[Record]` |
+| [`exclude`](#exclude) | [`exclude`](https://www.unisender.com/ru/support/api/contacts/exclude/) | `email` or `phone` with `list_ids`, or `contact_type` with `contact` | `contact_type`, `contact`, `email`, `phone`, `list_ids` | `ObjectResponse[Record]` |
+| [`export_contacts`](#export_contacts) | [`async/exportContacts`](https://www.unisender.com/ru/support/api/contacts/exportcontacts/) | None | `notify_url`, `list_id`, `field_names`, `email`, `phone`, `tag`, `email_status`, `phone_status`, `contact_status` | `TaskResponse` |
+| [`get_contact_count`](#get_contact_count) | [`getContactCount`](https://www.unisender.com/ru/support/api/contacts/getcontactcount/) | `list_id` and (`params` or explicit filters) | `params`, `tag_id`, `contact_type`, `search` | `ContactCountResponse` |
+| [`get_lists`](#get_lists) | [`getLists`](https://www.unisender.com/ru/support/api/contacts/getlists/) | None | None | `CollectionResponse[List]` |
+| [`get_total_contacts_count`](#get_total_contacts_count) | [`getTotalContactsCount`](https://www.unisender.com/ru/support/api/contacts/gettotalcontactscount/) | `login` | None | `TotalContactsResponse` |
+| [`import_contacts`](#import_contacts) | [`importContacts`](https://www.unisender.com/ru/support/api/contacts/importcontacts/) | `records` or `field_names` with `data` | `field_names`, `data`, `records`, `overwrite_tags`, `overwrite_lists`, `telegram_bot_channel_id` | `ImportResponse` |
+| [`subscribe`](#subscribe) | [`subscribe`](https://www.unisender.com/ru/support/api/contacts/subscribe/) | `list_ids` and (`email` or `fields`) | `fields`, `email`, `tags`, `double_optin`, `overwrite` | `SubscriptionResponse` |
+| [`update_list`](#update_list) | [`updateList`](https://www.unisender.com/ru/support/api/contacts/updatelist/) | `list_id`, `title` | `before_subscribe_url`, `after_subscribe_url`, `sub_user_rights` | `ObjectResponse[Record]` |
+| [`is_contact_in_lists`](#is_contact_in_lists) | [`isContactInLists`](https://www.unisender.com/ru/support/api/contacts/iscontactinlists/) | `email`, `list_ids`, `condition` | None | `Response[bool]` |
+| [`get_contact`](#get_contact) | [`getContact`](https://www.unisender.com/ru/support/api/contacts/getcontact/) | `email` | `include_lists`, `include_fields`, `include_details` | `ContactResponse` |
+| [`unsubscribe`](#unsubscribe) | [`unsubscribe`](https://www.unisender.com/ru/support/api/contacts/unsubscribe/) | `email` or `phone` with `list_ids`, or `contact_type` with `contact` | `contact_type`, `contact`, `email`, `phone`, `list_ids` | `ObjectResponse[Record]` |
+| [`cancel_campaign`](#cancel_campaign) | [`cancelCampaign`](https://www.unisender.com/ru/support/api/messages/cancel-campaign/) | `campaign_id` | None | `ObjectResponse[Record]` |
+| [`check_email`](#check_email) | [`checkEmail`](https://www.unisender.com/ru/support/api/messages/check-email/) | `email_id` | None | `CollectionResponse[EmailDelivery]` |
+| [`check_sms`](#check_sms) | [`checkSms`](https://www.unisender.com/ru/support/api/messages/check-sms/) | `sms_id` | None | `StatusResponse` |
+| [`create_campaign`](#create_campaign) | [`createCampaign`](https://www.unisender.com/ru/support/api/messages/createcampaign/) | `message_id` | `start_time`, `timezone`, `track_read`, `track_links`, `contacts`, `contacts_url`, `track_ga`, `payment_limit`, `payment_currency`, `ga_medium`, `ga_source`, `ga_campaign`, `ga_content`, `ga_term` | `CampaignCreatedResponse` |
+| [`create_email_message`](#create_email_message) | [`createEmailMessage`](https://www.unisender.com/ru/support/api/messages/createemailmessage/) | `list_id`; sender defaults; content or a template | `sender_name`, `sender_email`, `subject`, `body`, `text_body`, `generate_text`, `tag`, `attachments`, `lang`, `template_id`, `system_template_id`, `wrap_type`, `categories` | `MessageCreatedResponse` |
+| [`create_sms_message`](#create_sms_message) | [`createSmsMessage`](https://www.unisender.com/ru/support/api/messages/createsmsmessage/) | `sender`, `body`, `list_id` | `tag` | `MessageCreatedResponse` |
+| [`delete_message`](#delete_message) | [`deleteMessage`](https://www.unisender.com/ru/support/api/messages/deletemessage/) | `message_id` | None | `ObjectResponse[Record]` |
+| [`get_actual_message_version`](#get_actual_message_version) | [`getActualMessageVersion`](https://www.unisender.com/ru/support/api/messages/get-actual-message-version/) | `message_id` | None | `MessageVersionResponse` |
+| [`get_web_version`](#get_web_version) | [`getWebVersion`](https://www.unisender.com/ru/support/api/messages/getwebversion/) | `campaign_id` | None | `WebVersionResponse` |
+| [`send_email`](#send_email) | [`sendEmail`](https://www.unisender.com/ru/support/api/messages/sendemail/) | `email`, `subject`, `body`, `list_id`; sender defaults | `sender_name`, `sender_email`, `attachments`, `lang`, `track_read`, `track_links`, `cc`, `headers`, `images_as`, `ref_key`, `error_checking`, `metadata`, `reply_to`, `priority` | `SendResponse` |
+| [`send_sms`](#send_sms) | [`sendSms`](https://www.unisender.com/ru/support/api/messages/sendsms/) | `phone`, `sender`, `text` | None | `CollectionResponse[SmsReceipt]` |
+| [`send_test_email`](#send_test_email) | [`sendTestEmail`](https://www.unisender.com/ru/support/api/messages/sendtestemail/) | `email`, `id` | None | `MessageNoticeResponse` |
+| [`update_email_message`](#update_email_message) | [`updateEmailMessage`](https://www.unisender.com/ru/support/api/messages/updateemailmessage/) | `id` | `sender_name`, `sender_email`, `subject`, `body`, `list_id`, `text_body`, `lang`, `categories` | `MessageCreatedResponse` |
+| [`update_opt_in_email`](#update_opt_in_email) | [`updateOptInEmail`](https://www.unisender.com/ru/support/api/messages/updateoptinemail/) | `sender_name`, `sender_email`, `subject`, `body`, `list_id` | None | `ObjectResponse[Record]` |
+| [`get_sender_domain_list`](#get_sender_domain_list) | [`getSenderDomainList`](https://www.unisender.com/ru/support/api/messages/getsenderdomainlist/) | `username` | `domain`, `limit`, `offset` | `PageResponse[SenderDomainGroup]` |
+| [`get_campaign_common_stats`](#get_campaign_common_stats) | [`getCampaignCommonStats`](https://www.unisender.com/ru/support/api/statistics/get-campaign-common-stats/) | `campaign_id` | None | `CampaignStatsResponse` |
+| [`get_campaign_delivery_stats`](#get_campaign_delivery_stats) | [`async/getCampaignDeliveryStats`](https://www.unisender.com/ru/support/api/statistics/getcampaigndeliverystats/) | `campaign_id` | `notify_url`, `changed_since`, `field_ids` | `TaskResponse` |
+| [`get_campaign_status`](#get_campaign_status) | [`getCampaignStatus`](https://www.unisender.com/ru/support/api/statistics/getcampaignstatus/) | `campaign_id` | None | `StatusResponse` |
+| [`get_messages`](#get_messages) | [`getMessages`](https://www.unisender.com/ru/support/api/statistics/getmessages/) | `date_from`, `date_to` | `limit`, `offset` | `PageResponse[Message]` |
+| [`get_visited_links`](#get_visited_links) | [`getVisitedLinks`](https://www.unisender.com/ru/support/api/statistics/getvisitedlinks/) | `campaign_id` | `group` | `CollectionResponse[Record]` |
+| [`list_messages`](#list_messages) | [`listMessages`](https://www.unisender.com/ru/support/api/statistics/listmessages/) | `date_from`, `date_to` | `limit`, `offset` | `PageResponse[Message]` |
+| [`get_campaigns`](#get_campaigns) | [`getCampaigns`](https://www.unisender.com/ru/support/api/statistics/getcampaigns/) | `from` | `to`, `limit`, `offset` | `PageResponse[Campaign]` |
+| [`get_message`](#get_message) | [`getMessage`](https://www.unisender.com/ru/support/api/statistics/getmessage/) | `id` | None | `MessageResponse` |
+| [`get_task_result`](#get_task_result) | [`async/getTaskResult`](https://www.unisender.com/ru/support/api/statistics/../contacts/exportcontacts/) | `task_uuid` | None | `TaskResponse` |
+| [`create_email_template`](#create_email_template) | [`createEmailTemplate`](https://www.unisender.com/ru/support/api/templates/createemailtemplate/) | `title`, `subject`, `body` | `description`, `text_body`, `lang` | `IdentifierRecordResponse` |
+| [`delete_template`](#delete_template) | [`deleteTemplate`](https://www.unisender.com/ru/support/api/templates/deletetemplate/) | `template_id` | None | `ObjectResponse[Record]` |
+| [`get_template`](#get_template) | [`getTemplate`](https://www.unisender.com/ru/support/api/templates/gettemplate/) | `template_id` or `system_template_id` | `template_id`, `system_template_id` | `TemplateResponse` |
+| [`get_templates`](#get_templates) | [`getTemplates`](https://www.unisender.com/ru/support/api/templates/gettemplates/) | None | `type`, `date_from`, `date_to`, `limit`, `offset` | `PageResponse[Template]` |
+| [`list_templates`](#list_templates) | [`listTemplates`](https://www.unisender.com/ru/support/api/templates/listtemplates/) | None | `type`, `date_from`, `date_to`, `limit`, `offset` | `PageResponse[Template]` |
+| [`update_email_template`](#update_email_template) | [`updateEmailTemplate`](https://www.unisender.com/ru/support/api/templates/updateemailtemplate/) | `template_id` | `title`, `description`, `subject`, `body`, `text_body`, `lang` | `IdentifierRecordResponse` |
+| [`create_field`](#create_field) | [`createField`](https://www.unisender.com/ru/support/api/inputs/createfield/) | `name`, `type` | `public_name` | `IdentifierRecordResponse` |
+| [`delete_field`](#delete_field) | [`deleteField`](https://www.unisender.com/ru/support/api/inputs/deletefield/) | `id` | None | `ObjectResponse[Record]` |
+| [`delete_tag`](#delete_tag) | [`deleteTag`](https://www.unisender.com/ru/support/api/inputs/deletetag/) | `id` | None | `ObjectResponse[Record]` |
+| [`get_fields`](#get_fields) | [`getFields`](https://www.unisender.com/ru/support/api/inputs/getfields/) | None | None | `CollectionResponse[Field]` |
+| [`get_tags`](#get_tags) | [`getTags`](https://www.unisender.com/ru/support/api/inputs/gettags/) | None | None | `CollectionResponse[Tag]` |
+| [`update_field`](#update_field) | [`updateField`](https://www.unisender.com/ru/support/api/inputs/updatefield/) | `id`, `name` | `public_name` | `OptionalIdentifierResponse` |
+| [`get_contact_field_values`](#get_contact_field_values) | [`getContactFieldValues`](https://www.unisender.com/ru/support/api/inputs/getcontactfieldvalues/) | `email`, `field_ids` | None | `ContactFieldsResponse` |
+| [`create_subscriber_note`](#create_subscriber_note) | [`createSubscriberNote`](https://www.unisender.com/ru/support/api/notes/createsubscibernote/) | `subscriber_id`, `content` | None | `IdentifierRecordResponse` |
+| [`update_subscriber_note`](#update_subscriber_note) | [`updateSubscriberNote`](https://www.unisender.com/ru/support/api/notes/updatesubcribernote/) | `id`, `content` | None | `IdentifierRecordResponse` |
+| [`delete_subscriber_note`](#delete_subscriber_note) | [`deleteSubscriberNote`](https://www.unisender.com/ru/support/api/notes/deletesubscribernote/) | `id` | None | `ObjectResponse[Record]` |
+| [`get_subscriber_note`](#get_subscriber_note) | [`getSubscriberNote`](https://www.unisender.com/ru/support/api/notes/getsubscribernote/) | `id` | None | `NoteResponse` |
+| [`get_subscriber_notes`](#get_subscriber_notes) | [`getSubscriberNotes`](https://www.unisender.com/ru/support/api/notes/getsubscribernotes/) | `subscriber_id` | `limit`, `offset`, `order_type`, `order_by`, `is_pinned` | `PageResponse[Note]` |
+| [`set_hook`](#set_hook) | [`setHook`](https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/) | `hook_url`, `events` | `event_format`, `max_parallel`, `single_event`, `status` | `Response[json]` |
+| [`list_hooks`](#list_hooks) | [`listHooks`](https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/) | None | None | `CollectionResponse[Hook]` |
+| [`remove_hook`](#remove_hook) | [`removeHook`](https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/) | `hook_url` | None | `Response[json]` |
+| `track_events` | [Event Tracking](https://www.unisender.com/ru/support/api/event-tracking-api/) | `events` | None | `EventResponse` |
 ## Reading the contracts
@@ -75,7 +146,7 @@ Expand an operation below for its accepted Ruby types and result shape. `id` mea
 Named methods accept Arrays for the documented comma-separated fields and join them before encoding. Other nested arrays and hashes retain bracket indices. An empty String/Array/Hash is rejected for a required value. Method-specific constraints beyond the structural checks are validated by the service; refer to the linked official page for account permissions, current limits, and additional response fields.
-All result descriptions refer to `response.result`, not the enclosing response. Unknown fields remain in `response.data`, even when a result type lists only its guaranteed fields. API errors raise `APIError`, HTTP errors raise `HTTPError`, malformed successful responses raise `InvalidResponseError`, and connection failures raise `TransportError`; none should be interpreted as an empty success. Import and send operations can also return per-record failures inside a successful result.
+Named-operation results are immutable typed records or collections. The wire shapes below describe `response.data`; records expose documented fields and string-key lookup. HTTP metadata uses `response.http_status`. See [the migration guide](migration-0.2.md). Unknown fields remain in `response.data`, even when a result type lists only its guaranteed fields. API errors raise `APIError`, HTTP errors raise `HTTPError`, malformed successful responses raise `InvalidResponseError`, and connection failures raise `TransportError`; none should be interpreted as an empty success. Import and send operations can also return per-record failures inside a successful result.
 ## Operation contracts
@@ -88,9 +159,9 @@ All result descriptions refer to `response.result`, not the enclosing response.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `title` | `String` | Required |
-| `before_subscribe_url` | `String` | Optional, omitted |
-| `after_subscribe_url` | `String` | Optional, omitted |
-| `sub_user_rights` | `params` | Optional, omitted |
+| `before_subscribe_url` | `String \| nil` | Optional, omitted |
+| `after_subscribe_url` | `String \| nil` | Optional, omitted |
+| `sub_user_rights` | `params \| nil` | Optional, omitted |
 **Result:** Object with `id`, the new list identifier.
@@ -108,7 +179,7 @@ The title must be unique within the account. `sub_user_rights` maps user IDs to
 | --- | --- | --- |
 | `list_id` | `id` | Required |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization. Deletes the list; review the upstream consequences before use.
+**Result:** Empty JSON result on success. An empty legacy array is normalized to an empty record; `data` retains the original shape. Deletes the list; review the upstream consequences before use.
 </details>
@@ -120,11 +191,13 @@ The title must be unique within the account. `sub_user_rights` maps user IDs to
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `contact_type` | `String` | Required |
-| `contact` | `String` | Required |
-| `list_ids` | `String \| Array[id]` | Optional, omitted |
+| `contact_type` | `contact_type?` | Required with contact |
+| `contact` | `String?` | Required with contact_type |
+| `email` | `String?` | Alternative contact selector; requires list_ids |
+| `phone` | `String?` | Alternative contact selector; requires list_ids |
+| `list_ids` | `String \| Array[id] \| nil` | Optional, omitted |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization. Removes membership in the selected lists.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape. Removes membership in the selected lists.
 `contact_type` is `"email"` or `"phone"`. Omitted `list_ids` applies the upstream account-wide behavior; provide explicit IDs when intending to affect selected lists only.
@@ -138,15 +211,15 @@ The title must be unique within the account. `sub_user_rights` maps user IDs to
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `notify_url` | `String` | Optional, omitted |
-| `list_id` | `id` | Optional, omitted |
-| `field_names` | `Array[String]` | Optional, omitted |
-| `email` | `String` | Optional, omitted |
-| `phone` | `String` | Optional, omitted |
-| `tag` | `String` | Optional, omitted |
-| `email_status` | `String` | Optional, omitted |
-| `phone_status` | `String` | Optional, omitted |
-| `contact_status` | `String` | Optional, omitted |
+| `notify_url` | `String \| nil` | Optional, omitted |
+| `list_id` | `id \| nil` | Optional, omitted |
+| `field_names` | `Array[String] \| nil` | Optional, omitted |
+| `email` | `String \| nil` | Optional, omitted |
+| `phone` | `String \| nil` | Optional, omitted |
+| `tag` | `String \| nil` | Optional, omitted |
+| `email_status` | `String \| nil` | Optional, omitted |
+| `phone_status` | `String \| nil` | Optional, omitted |
+| `contact_status` | `String \| nil` | Optional, omitted |
 **Result:** Object with `task_uuid` and initial `status`. Poll `get_task_result`, or use `wait_for_task`; a completed job provides `file_to_download`.
@@ -161,9 +234,12 @@ The title must be unique within the account. `sub_user_rights` maps user IDs to
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `list_id` | `id` | Required |
-| `params` | `params` | Required |
+| `params` | `params?` | Alternative to explicit filters |
+| `tag_id` | `id?` | Optional, omitted |
+| `contact_type` | `contact_type \| "address" \| nil` | Required when search is supplied |
+| `search` | `String?` | Optional, omitted |
-**Result:** Object with `listId`, `searchParams`, and `count`. The documented `count` is a String, not an Integer.
+**Wire result:** Object with `listId`, `searchParams`, and a String `count`. The typed `response.count` reader returns an Integer.
 `params` must contain at least one filter. Use `tagId`, `type` (`"address"` or `"phone"`), and optionally `search`; `search` requires `type`.
@@ -203,15 +279,16 @@ No operation arguments.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `field_names` | `Array[String]` | Required |
-| `data` | `Array[Array[parameter]]` | Required |
-| `overwrite_tags` | `flag` | Optional, omitted |
-| `overwrite_lists` | `flag` | Optional, omitted |
-| `telegram_bot_channel_id` | `String` | Optional, omitted |
+| `field_names` | `Array[String]?` | Required with data |
+| `data` | `Array[Array[parameter]]?` | Required with field_names |
+| `records` | `Enumerable[params]?` | Alternative to field_names and data |
+| `overwrite_tags` | `flag \| nil` | Optional, omitted |
+| `overwrite_lists` | `flag \| nil` | Optional, omitted |
+| `telegram_bot_channel_id` | `String \| nil` | Optional, omitted |
 **Result:** Object with Integer counters `total`, `inserted`, `updated`, `deleted`, `new_emails`, and `invalid`; `log` contains per-row `index`, `code`, and `message`. A successful response can include rejected rows. Inspect `invalid` and `log`.
-`field_names` must be unique and include `"email"`. Supply 1 to 500 rows with exactly one cell per column. `overwrite_tags` and `overwrite_lists` default to 0; setting them to 1 replaces existing associations. `email_list_ids` is a comma-separated cell, not an Array. `telegram_bot_channel_id` is required upstream when a row contains `telegram_user_id`.
+`records:` is mutually exclusive with `field_names:` and `data:`. Record keys must be consistent and include email; the first record determines column order. Arrays validate before sending, while streams validate as consumed. `field_names` must be unique and include `"email"`. Supply 1 to 500 rows with exactly one cell per column. `overwrite_tags` and `overwrite_lists` default to 0; setting them to 1 replaces existing associations. `email_list_ids` is a comma-separated cell, not an Array. `telegram_bot_channel_id` is required upstream when a row contains `telegram_user_id`.
 </details>
@@ -224,14 +301,15 @@ No operation arguments.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `list_ids` | `String \| Array[id]` | Required |
-| `fields` | `params` | Required |
-| `tags` | `String \| Array[id]` | Optional, omitted |
-| `double_optin` | `Integer` | Optional, omitted |
-| `overwrite` | `Integer` | Optional, omitted |
+| `fields` | `params?` | Required unless email is supplied |
+| `email` | `String?` | Required unless supplied in fields |
+| `tags` | `String \| Array[id] \| nil` | Optional, omitted |
+| `double_optin` | `Integer \| :request_confirmation \| :already_confirmed \| :confirm_if_needed \| nil` | Optional, omitted |
+| `overwrite` | `Integer \| :preserve \| :replace \| :update \| nil` | Optional, omitted |
 **Result:** Object with `person_id`, the contact identifier. Success does not mean the contact has confirmed subscription.
-`fields` must include `email`; custom names are case-sensitive. `double_optin` accepts 0 (confirmation email), 3 (prior consent, no confirmation email), or 4 (reuse an already-confirmed contact, otherwise send confirmation). `overwrite` accepts 0 (preserve existing), 1 (replace fields, tags, and list membership), or 2 (update supplied fields). Up to ten tags are allowed.
+Supply `email:` directly or include email in `fields:`; custom names are case-sensitive. Conflicting email values raise before sending. Named consent modes are `:request_confirmation` (0), `:already_confirmed` (3), and `:confirm_if_needed` (4). Named overwrite modes are `:preserve` (0), `:replace` (1), and `:update` (2). `double_optin` accepts 0 (confirmation email), 3 (prior consent, no confirmation email), or 4 (reuse an already-confirmed contact, otherwise send confirmation). `overwrite` accepts 0 (preserve existing), 1 (replace fields, tags, and list membership), or 2 (update supplied fields). Up to ten tags are allowed.
 </details>
@@ -245,11 +323,11 @@ No operation arguments.
 | --- | --- | --- |
 | `list_id` | `id` | Required |
 | `title` | `String` | Required |
-| `before_subscribe_url` | `String` | Optional, omitted |
-| `after_subscribe_url` | `String` | Optional, omitted |
-| `sub_user_rights` | `params` | Optional, omitted |
+| `before_subscribe_url` | `String \| nil` | Optional, omitted |
+| `after_subscribe_url` | `String \| nil` | Optional, omitted |
+| `sub_user_rights` | `params \| nil` | Optional, omitted |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape.
 </details>
@@ -280,9 +358,9 @@ No operation arguments.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `email` | `String` | Required |
-| `include_lists` | `flag` | Optional, omitted |
-| `include_fields` | `flag` | Optional, omitted |
-| `include_details` | `flag` | Optional, omitted |
+| `include_lists` | `flag \| nil` | Optional, omitted |
+| `include_fields` | `flag \| nil` | Optional, omitted |
+| `include_details` | `flag \| nil` | Optional, omitted |
 **Result:** Object with nested `email` contact details. `phone`, `lists`, and custom `fields` depend on the contact and include options. Access the address as `result.fetch("email").fetch("email")`, not `result.fetch("email")` alone.
@@ -296,11 +374,13 @@ No operation arguments.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `contact_type` | `String` | Required |
-| `contact` | `String` | Required |
-| `list_ids` | `String \| Array[id]` | Optional, omitted |
+| `contact_type` | `contact_type?` | Required with contact |
+| `contact` | `String?` | Required with contact_type |
+| `email` | `String?` | Alternative contact selector; requires list_ids |
+| `phone` | `String?` | Alternative contact selector; requires list_ids |
+| `list_ids` | `String \| Array[id] \| nil` | Optional, omitted |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization. Unsubscribes the specified contact from the selected lists.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape. Unsubscribes the specified contact from the selected lists.
 `contact_type` is `"email"` or `"phone"`. Omitted `list_ids` applies the upstream account-wide behavior; provide explicit IDs when intending to affect selected lists only.
@@ -357,20 +437,20 @@ No operation arguments.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `message_id` | `id` | Required |
-| `start_time` | `String` | Optional, omitted |
-| `timezone` | `String` | Optional, omitted |
-| `track_read` | `flag` | Optional, omitted |
-| `track_links` | `flag` | Optional, omitted |
-| `contacts` | `String \| Array[id]` | Optional, omitted |
-| `contacts_url` | `String` | Optional, omitted |
-| `track_ga` | `flag` | Optional, omitted |
-| `payment_limit` | `Integer \| Float` | Optional, omitted |
-| `payment_currency` | `String` | Optional, omitted |
-| `ga_medium` | `String` | Optional, omitted |
-| `ga_source` | `String` | Optional, omitted |
-| `ga_campaign` | `String` | Optional, omitted |
-| `ga_content` | `String` | Optional, omitted |
-| `ga_term` | `String` | Optional, omitted |
+| `start_time` | `String \| Time \| nil` | Optional, omitted |
+| `timezone` | `String \| nil` | Optional, omitted |
+| `track_read` | `flag \| nil` | Optional, omitted |
+| `track_links` | `flag \| nil` | Optional, omitted |
+| `contacts` | `String \| Array[id] \| nil` | Optional, omitted |
+| `contacts_url` | `String \| nil` | Optional, omitted |
+| `track_ga` | `flag \| nil` | Optional, omitted |
+| `payment_limit` | `Integer \| Float \| nil` | Optional, omitted |
+| `payment_currency` | `String \| nil` | Optional, omitted |
+| `ga_medium` | `String \| nil` | Optional, omitted |
+| `ga_source` | `String \| nil` | Optional, omitted |
+| `ga_campaign` | `String \| nil` | Optional, omitted |
+| `ga_content` | `String \| nil` | Optional, omitted |
+| `ga_term` | `String \| nil` | Optional, omitted |
 **Result:** Object with `campaign_id` and String `status`, such as `scheduled` or `waits_censor`. `count` is deprecated and documented as zero. Accepted does not mean delivered.
@@ -386,20 +466,20 @@ No operation arguments.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `sender_name` | `String` | Required |
-| `sender_email` | `String` | Required |
 | `list_id` | `id` | Required |
-| `subject` | `String` | Optional, omitted |
-| `body` | `String` | Optional, omitted |
-| `text_body` | `String` | Optional, omitted |
-| `generate_text` | `flag` | Optional, omitted |
-| `tag` | `String` | Optional, omitted |
-| `attachments` | `Hash[String, String]` | Optional, omitted |
-| `lang` | `String` | Optional, omitted |
-| `template_id` | `id` | Optional, omitted |
-| `system_template_id` | `id` | Optional, omitted |
-| `wrap_type` | `String` | Optional, omitted |
-| `categories` | `String \| Array[id]` | Optional, omitted |
+| `sender_name` | `String?` | Required unless configured as a default |
+| `sender_email` | `String?` | Required unless configured as a default |
+| `subject` | `String \| nil` | Required without a template |
+| `body` | `String \| nil` | Required without a template |
+| `text_body` | `String \| nil` | Optional, omitted |
+| `generate_text` | `flag \| nil` | Optional, omitted |
+| `tag` | `String \| nil` | Optional, omitted |
+| `attachments` | `Hash[String, String] \| Attachment \| Array[Attachment] \| nil` | Optional, omitted |
+| `lang` | `String \| nil` | Optional, omitted |
+| `template_id` | `id \| nil` | Optional, omitted |
+| `system_template_id` | `id \| nil` | Optional, omitted |
+| `wrap_type` | `String \| nil` | Optional, omitted |
+| `categories` | `String \| Array[id] \| nil` | Optional, omitted |
 **Result:** Object with `message_id`. Creates a message without sending it. Pass the identifier to `create_campaign` to send.
@@ -418,7 +498,7 @@ Supply nonempty `subject` and `body`, or select `template_id` / `system_template
 | `sender` | `String` | Required |
 | `body` | `String` | Required |
 | `list_id` | `id` | Required |
-| `tag` | `String` | Optional, omitted |
+| `tag` | `String \| nil` | Optional, omitted |
 **Result:** Object with `message_id`. Creates a message without sending it.
@@ -434,7 +514,7 @@ Supply nonempty `subject` and `body`, or select `template_id` / `system_template
 | --- | --- | --- |
 | `message_id` | `id` | Required |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape.
 </details>
@@ -475,21 +555,23 @@ Supply nonempty `subject` and `body`, or select `template_id` / `system_template
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `email` | `String` | Required |
-| `sender_name` | `String` | Required |
-| `sender_email` | `String` | Required |
 | `subject` | `String` | Required |
 | `body` | `String` | Required |
 | `list_id` | `id` | Required |
-| `attachments` | `Hash[String, String]` | Optional, omitted |
-| `lang` | `String` | Optional, omitted |
-| `track_read` | `flag` | Optional, omitted |
-| `track_links` | `flag` | Optional, omitted |
-| `cc` | `String` | Optional, omitted |
-| `headers` | `String \| params` | Optional, omitted |
-| `images_as` | `String` | Optional, omitted |
-| `ref_key` | `String` | Optional, omitted |
-| `error_checking` | `flag` | Optional, omitted |
-| `metadata` | `params` | Optional, omitted |
+| `sender_name` | `String?` | Required unless configured as a default |
+| `sender_email` | `String?` | Required unless configured as a default |
+| `attachments` | `Hash[String, String] \| Attachment \| Array[Attachment] \| nil` | Optional, omitted |
+| `lang` | `String \| nil` | Optional, omitted |
+| `track_read` | `flag \| nil` | Optional, omitted |
+| `track_links` | `flag \| nil` | Optional, omitted |
+| `cc` | `String \| nil` | Optional, omitted |
+| `headers` | `String \| params \| nil` | Optional, omitted |
+| `images_as` | `String \| Symbol \| nil` | Optional, omitted |
+| `ref_key` | `String \| nil` | Optional, omitted |
+| `error_checking` | `flag \| nil` | Optional, defaults to true; nil omits the field |
+| `metadata` | `params \| nil` | Optional, omitted |
+| `reply_to` | `String \| nil` | Optional, omitted |
+| `priority` | `String \| nil` | Optional, omitted |
 **Result:** With `error_checking: 1` or `cc`, an Array of per-recipient results containing `index`, `email`, and accepted message `id`. Without either, the legacy result is an Object with `email_id`. With `error_checking: 1`, also inspect recipient `errors`; the top-level success envelope alone is insufficient.
@@ -505,7 +587,7 @@ Use a verified sender and consenting recipients. `attachments` maps filenames to
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `phone` | `String` | Required |
+| `phone` | `String \| Array[String]` | Required |
 | `sender` | `String` | Required |
 | `text` | `String` | Required |
@@ -539,14 +621,14 @@ Use the international phone format and an approved sender. Sending is never auto
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `id` | `id` | Required |
-| `sender_name` | `String` | Optional, omitted |
-| `sender_email` | `String` | Optional, omitted |
-| `subject` | `String` | Optional, omitted |
-| `body` | `String` | Optional, omitted |
-| `list_id` | `id` | Optional, omitted |
-| `text_body` | `String` | Optional, omitted |
-| `lang` | `String` | Optional, omitted |
-| `categories` | `String \| Array[id]` | Optional, omitted |
+| `sender_name` | `String \| nil` | Optional, omitted |
+| `sender_email` | `String \| nil` | Optional, omitted |
+| `subject` | `String \| nil` | Optional, omitted |
+| `body` | `String \| nil` | Optional, omitted |
+| `list_id` | `id \| nil` | Optional, omitted |
+| `text_body` | `String \| nil` | Optional, omitted |
+| `lang` | `String \| nil` | Optional, omitted |
+| `categories` | `String \| Array[id] \| nil` | Optional, omitted |
 **Result:** Object with `message_id`. Retain the returned identifier because editing an already-sent message can create a new version.
@@ -566,7 +648,7 @@ Use the international phone format and an approved sender. Sending is never auto
 | `body` | `String` | Required |
 | `list_id` | `id` | Required |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization. Updates the list confirmation message.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape. Updates the list confirmation message.
 </details>
@@ -579,9 +661,9 @@ Use the international phone format and an approved sender. Sending is never auto
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `username` | `String` | Required |
-| `domain` | `String` | Optional, omitted |
-| `limit` | `Integer` | Optional, omitted |
-| `offset` | `Integer` | Optional, omitted |
+| `domain` | `String \| nil` | Optional, omitted |
+| `limit` | `Integer \| nil` | Optional, defaults to 100 |
+| `offset` | `Integer \| nil` | Optional, omitted |
 **Result:** Array of groups containing `status` and `domains`; each domain has fields such as `Domain` and `Status`. Preserve the upstream capitalization. Pagination counts domains, not groups.
@@ -610,9 +692,9 @@ Use the international phone format and an approved sender. Sending is never auto
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `campaign_id` | `id` | Required |
-| `notify_url` | `String` | Optional, omitted |
-| `changed_since` | `String` | Optional, omitted |
-| `field_ids` | `Array[id]` | Optional, omitted |
+| `notify_url` | `String \| nil` | Optional, omitted |
+| `changed_since` | `String \| Time \| nil` | Optional, omitted |
+| `field_ids` | `Array[id] \| nil` | Optional, omitted |
 **Result:** Object with `task_uuid` and initial `status`, followed by a download URL when the asynchronous report completes.
@@ -640,14 +722,14 @@ Use the international phone format and an approved sender. Sending is never auto
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `date_from` | `String` | Required |
-| `date_to` | `String` | Required |
-| `limit` | `Integer` | Optional, omitted |
-| `offset` | `Integer` | Optional, omitted |
+| `date_from` | `String \| Time` | Required |
+| `date_to` | `String \| Time` | Required |
+| `limit` | `Integer \| nil` | Optional, defaults to 100 |
+| `offset` | `Integer \| nil` | Optional, omitted |
 **Result:** Array of message objects, including identifiers, content, sender information, and version metadata. Field availability depends on email versus SMS.
-Date filters use UTC `YYYY-MM-DD HH:MM:SS`. `limit` is 1 to 100 (default 50), and `offset` starts at zero.
+Date filters use UTC `YYYY-MM-DD HH:MM`. `limit` is 1 to 100 (default 50), and `offset` starts at zero.
 </details>
@@ -660,7 +742,7 @@ Date filters use UTC `YYYY-MM-DD HH:MM:SS`. `limit` is 1 to 100 (default 50), an
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `campaign_id` | `id` | Required |
-| `group` | `flag` | Optional, omitted |
+| `group` | `flag \| nil` | Optional, omitted |
 **Result:** Object with `fields` (column names) and `data` (rows). Interpret each row using the matching column index.
@@ -674,10 +756,10 @@ Date filters use UTC `YYYY-MM-DD HH:MM:SS`. `limit` is 1 to 100 (default 50), an
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `date_from` | `String` | Required |
-| `date_to` | `String` | Required |
-| `limit` | `Integer` | Optional, omitted |
-| `offset` | `Integer` | Optional, omitted |
+| `date_from` | `String \| Time` | Required |
+| `date_to` | `String \| Time` | Required |
+| `limit` | `Integer \| nil` | Optional, defaults to 100 |
+| `offset` | `Integer \| nil` | Optional, omitted |
 **Result:** Array of message summary objects. Use `get_message` when message content is needed.
@@ -693,10 +775,10 @@ Date filters use UTC `YYYY-MM-DD HH:MM:SS`. `limit` is 1 to 100 (default 50), an
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `from` | `String` | Required |
-| `to` | `String` | Optional, omitted |
-| `limit` | `Integer` | Optional, omitted |
-| `offset` | `Integer` | Optional, omitted |
+| `from` | `String \| Time` | Required |
+| `to` | `String \| Time \| nil` | Optional, omitted |
+| `limit` | `Integer \| nil` | Optional, defaults to 100 |
+| `offset` | `Integer \| nil` | Optional, omitted |
 **Result:** Array of campaign objects with identifiers and campaign metadata. Supports offset pagination.
@@ -743,9 +825,9 @@ Date filters use UTC `YYYY-MM-DD HH:MM:SS`. `limit` is 1 to 100 (default 50), an
 | `title` | `String` | Required |
 | `subject` | `String` | Required |
 | `body` | `String` | Required |
-| `description` | `String` | Optional, omitted |
-| `text_body` | `String` | Optional, omitted |
-| `lang` | `String` | Optional, omitted |
+| `description` | `String \| nil` | Optional, omitted |
+| `text_body` | `String \| nil` | Optional, omitted |
+| `lang` | `String \| nil` | Optional, omitted |
 **Result:** Object with the new template `id`.
@@ -761,7 +843,7 @@ Date filters use UTC `YYYY-MM-DD HH:MM:SS`. `limit` is 1 to 100 (default 50), an
 | --- | --- | --- |
 | `template_id` | `id` | Required |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape.
 </details>
@@ -773,8 +855,8 @@ Date filters use UTC `YYYY-MM-DD HH:MM:SS`. `limit` is 1 to 100 (default 50), an
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `template_id` | `id` | Optional, omitted |
-| `system_template_id` | `id` | Optional, omitted |
+| `template_id` | `id \| nil` | Optional, omitted |
+| `system_template_id` | `id \| nil` | Optional, omitted |
 **Result:** Object describing the selected template. User and system templates can have different fields; content fields include `subject`, `body`, and `lang_code` where applicable.
@@ -790,11 +872,11 @@ Provide `template_id` or `system_template_id`; neither is required individually,
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `type` | `String` | Optional, omitted |
-| `date_from` | `String` | Optional, omitted |
-| `date_to` | `String` | Optional, omitted |
-| `limit` | `Integer` | Optional, omitted |
-| `offset` | `Integer` | Optional, omitted |
+| `type` | `template_type \| nil` | Optional, omitted |
+| `date_from` | `String \| Time \| nil` | Optional, omitted |
+| `date_to` | `String \| Time \| nil` | Optional, omitted |
+| `limit` | `Integer \| nil` | Optional, defaults to 100 |
+| `offset` | `Integer \| nil` | Optional, omitted |
 **Result:** Array of template objects with identifiers, titles, content, and metadata. User-only fields include `body`; system templates can provide preview URLs instead.
@@ -810,11 +892,11 @@ Provide `template_id` or `system_template_id`; neither is required individually,
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
-| `type` | `String` | Optional, omitted |
-| `date_from` | `String` | Optional, omitted |
-| `date_to` | `String` | Optional, omitted |
-| `limit` | `Integer` | Optional, omitted |
-| `offset` | `Integer` | Optional, omitted |
+| `type` | `template_type \| nil` | Optional, omitted |
+| `date_from` | `String \| Time \| nil` | Optional, omitted |
+| `date_to` | `String \| Time \| nil` | Optional, omitted |
+| `limit` | `Integer \| nil` | Optional, defaults to 100 |
+| `offset` | `Integer \| nil` | Optional, omitted |
 **Result:** Array of template summary objects. Use `get_template` for a selected template.
@@ -831,12 +913,12 @@ Provide `template_id` or `system_template_id`; neither is required individually,
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `template_id` | `id` | Required |
-| `title` | `String` | Optional, omitted |
-| `description` | `String` | Optional, omitted |
-| `subject` | `String` | Optional, omitted |
-| `body` | `String` | Optional, omitted |
-| `text_body` | `String` | Optional, omitted |
-| `lang` | `String` | Optional, omitted |
+| `title` | `String \| nil` | Optional, omitted |
+| `description` | `String \| nil` | Optional, omitted |
+| `subject` | `String \| nil` | Optional, omitted |
+| `body` | `String \| nil` | Optional, omitted |
+| `text_body` | `String \| nil` | Optional, omitted |
+| `lang` | `String \| nil` | Optional, omitted |
 **Result:** Object with the updated template `id`.
@@ -852,7 +934,7 @@ Provide `template_id` or `system_template_id`; neither is required individually,
 | --- | --- | --- |
 | `name` | `String` | Required |
 | `type` | `String` | Required |
-| `public_name` | `String` | Optional, omitted |
+| `public_name` | `String \| nil` | Optional, omitted |
 **Result:** Object with the new field `id`.
@@ -868,7 +950,7 @@ Provide `template_id` or `system_template_id`; neither is required individually,
 | --- | --- | --- |
 | `id` | `id` | Required |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape.
 </details>
@@ -882,7 +964,7 @@ Provide `template_id` or `system_template_id`; neither is required individually,
 | --- | --- | --- |
 | `id` | `id` | Required |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape.
 </details>
@@ -920,7 +1002,7 @@ No operation arguments.
 | --- | --- | --- |
 | `id` | `id` | Required |
 | `name` | `String` | Required |
-| `public_name` | `String` | Optional, omitted |
+| `public_name` | `String \| nil` | Optional, omitted |
 **Result:** The documented top-level Object contains the updated field `id`. Legacy `result` envelopes are also accepted.
@@ -981,7 +1063,7 @@ No operation arguments.
 | --- | --- | --- |
 | `id` | `id` | Required |
-**Result:** Empty JSON result on success. The documented object shape and legacy array responses are preserved without normalization.
+**Result:** Empty JSON result on success. Named calls normalize an empty legacy array to an empty record; `data` retains the wire shape.
 </details>
@@ -1008,11 +1090,11 @@ No operation arguments.
 | Keyword | Ruby type | Presence |
 | --- | --- | --- |
 | `subscriber_id` | `id` | Required |
-| `limit` | `Integer` | Optional, omitted |
-| `offset` | `Integer` | Optional, omitted |
-| `order_type` | `String` | Optional, omitted |
-| `order_by` | `String` | Optional, omitted |
-| `is_pinned` | `flag` | Optional, omitted |
+| `limit` | `Integer \| nil` | Optional, defaults to 100 |
+| `offset` | `Integer \| nil` | Optional, omitted |
+| `order_type` | `note_order \| nil` | Optional, omitted |
+| `order_by` | `note_field \| nil` | Optional, omitted |
+| `is_pinned` | `flag \| nil` | Optional, omitted |
 **Result:** Array of note objects for the subscriber. Supports offset pagination.
@@ -1034,13 +1116,93 @@ Supply 1 to 25 events. Each event requires a `name` of 1 to 40 characters and an
 </details>
+## Typed result readers
+Records support `[]`, `fetch`, and `dig` with exact upstream keys. `to_h` returns a detached mutable copy.
+Documented optional fields return `nil`; unknown fields remain accessible through lookup and the raw response.
+Object responses expose their result readers directly. Collection elements expose the readers in this table.
+| Result | Readers |
+| --- | --- |
+| `Campaign` | `status`, `subject`, `id` |
+| `CampaignCreated` | `count`, `campaign_id`, `status` |
+| `CampaignStats` | `total`, `sent`, `delivered`, `read_unique`, `read_all`, `clicked_unique`, `clicked_all`, `unsubscribed`, `spam` |
+| `Contact` | `email`, `email_address`, `phone`, `phone_number`, `lists`, `fields` |
+| `ContactCount` | `count` |
+| `ContactFields` | `field_values` |
+| `ContactList` | `status`, `added_at`, `id` |
+| `EmailContact` | `email`, `status`, `availability`, `added_at`, `last_send_datetime`, `last_delivery_datetime`, `last_read_datetime`, `last_click_datetime`, `rating` |
+| `EmailDelivery` | `id`, `status` |
+| `EventResult` | `complete?`, `partial?`, `uncertain?`, `failures` |
+| `Failure` | `index`, `code`, `message`, `warning?`, `with_offset` |
+| `Field` | `name`, `type`, `id` |
+| `Hook` | `url`, `event_format`, `max_parallel`, `single_event`, `status`, `events`, `id` |
+| `IdentifierRecord` | `id` |
+| `ImportResult` | `row_warnings`, `inserted`, `updated`, `deleted`, `new_emails`, `total`, `invalid`, `complete?`, `partial?`, `uncertain?`, `failures` |
+| `List` | `title`, `id` |
+| `Message` | `subject`, `body`, `sender_name`, `sender_email`, `id` |
+| `MessageCreated` | `message_id` |
+| `MessageNotice` | `message` |
+| `MessageVersion` | `message_id`, `actual_version_id` |
+| `Note` | `user_id`, `subscriber_id`, `origin`, `is_pinned`, `created_at`, `updated_at`, `pinned_at`, `content`, `id` |
+| `OptionalIdentifier` | `id` |
+| `PhoneContact` | `phone`, `status`, `availability`, `added_at` |
+| `RecipientResult` | `id`, `index`, `email`, `failures`, `accepted?` |
+| `SendResult` | `accepted_recipients`, `rejected_recipients`, `unknown_recipients`, `accepted_ids`, `recipients`, `email_id`, `complete?`, `partial?`, `uncertain?`, `failures` |
+| `SenderDomain` | `domain`, `status`, `key` |
+| `SenderDomainGroup` | `status`, `domains` |
+| `SmsReceipt` | `sms_id`, `price`, `currency` |
+| `Status` | `status` |
+| `Subscription` | `person_id` |
+| `Tag` | `name`, `id` |
+| `TaskResult` | `task_uuid`, `status`, `file_to_download` |
+| `Template` | `title`, `subject`, `body`, `id` |
+| `TotalContacts` | `total` |
+| `WebVersion` | `letter_id`, `web_letter_link` |
+| `WebhookEvent` | `event_name`, `event_time`, `event_data` |
+| `WebhookNotification` | `users`, `events` |
+| `WebhookUser` | `login`, `events` |
+Report responses also expose `raise_for_partial_failure!`.
+A `BatchReport` exposes `responses`, `completed_batches`, `total`, `invalid`, `failures`, `complete?`, `partial?`, and `uncertain?`.
+Its totals return `nil` when the outcome does not provide reliable import counts.
+Task handles expose `task_uuid`, `wait`, and `download_to`; their result retains the original task fields. Polling request errors keep their original error class and expose `task_uuid` plus `last_response` (nil before any observed task state).
 ## Documentation decisions
+### Webhook management
+<a id="set_hook"></a>
+#### `set_hook`
+| Keyword | Ruby type | Presence |
+| --- | --- | --- |
+| `hook_url` | `String` | Required |
+| `events` | `Hash[String \| Symbol, String \| Array[String \| Integer]]` | Required |
+| `event_format` | `:json_post \| :json_post_gzip \| :http_get \| String` | Optional, defaults to json_post_gzip |
+| `max_parallel` | `Integer?` | Optional, omitted |
+| `single_event` | `flag` | Optional, defaults to false (0 on the wire) |
+| `status` | `:active \| :disabled \| String` | Optional, defaults to active |
+<a id="list_hooks"></a>
+#### `list_hooks`
+No operation arguments.
+<a id="remove_hook"></a>
+#### `remove_hook`
+| Keyword | Ruby type | Presence |
+| --- | --- | --- |
+| `hook_url` | `String` | Required |
+See the [receiver guide](webhooks.md) for registration behavior and bounded verification.
 Successful `sendTestEmail` and `updateField` examples omit the `result` envelope. These two operations also accept their documented top-level success fields. Other operations still require `result`, and `error` always takes precedence.
 1. **D1:** The supplied [OpenAPI repository](https://gitflic.ru/project/unisender/unigo-openapi) targets UniSender Go, which has a different host and protocol. This gem does not use that specification.
-2. **D2:** Contact exports and delivery reports use `async/exportContacts` and `async/getCampaignDeliveryStats`. Both share `async/getTaskResult`. The gem returns the download URL without requesting it or forwarding credentials to it.
+2. **D2:** Contact exports and delivery reports use `async/exportContacts` and `async/getCampaignDeliveryStats`. Both share `async/getTaskResult`. The gem returns the download URL. Only an explicit `download_to` requests it, using a separate connection without API credentials.
 3. **D3:** Note page titles misspell create and update operations. Their request examples use `createSubscriberNote` and `updateSubscriberNote`; the gem follows those request URLs.
 4. **D4:** Event Tracking's endpoint definition specifies `https://event.unisender.com/v1/events/`, but its examples omit `/v1`. The gem follows the endpoint definition. The page also shows both a string `error` and structured `details`; `EventError#details` accepts either representation. HTTP 400 can mean partial acceptance.
 5. **D5:** The create-email page allows templates to supply subject and body. Both template selectors satisfy this alternative; the gem does not invent precedence if both are supplied. Its syntax lists `categories`, although its argument table omits it; the gem accepts that documented keyword.
@@ -1049,15 +1211,38 @@ Successful `sendTestEmail` and `updateField` examples omit the `result` envelope
 ## Convenience operations
+`client.validate!(operation, **arguments)` checks named request arguments, defaults, normalization, and encoding without networking.
+It returns `true` or raises a validation error. It also accepts `:track_events` and `:send_campaign`.
+Low-level requests and multi-request iterators are not supported. Import validation consumes supplied records up to the direct-request bound.
 | Helper | Behavior |
 | --- | --- |
 | `each_page(method, page_size: 100, max_pages: 1000, **params)` | Lazy Enumerator of responses for `get_campaigns`, `get_messages`, `list_messages`, `get_templates`, `list_templates`, `get_sender_domain_list`, and `get_subscriber_notes`. An optional `offset` starts iteration. Stops at a short or empty page; raises at the page bound. Offset pagination is not a server snapshot. |
-| `import_contacts_in_batches(field_names:, data:, batch_size: 500, ...)` | Lazy sequential import of an Enumerable of rows. Accepts `overwrite_tags`, `overwrite_lists`, and `telegram_bot_channel_id`. Stops on request failures or a nonzero `invalid` count. |
-| `track_events_in_batches(events:, batch_size: 25)` | Lazy sequential event batches. Each request must also meet the 130 KiB payload limit. Use a smaller batch size for large events. |
+| `import_contacts_in_batches(records: ..., batch_size: 500, ...)` | Immediate sequential import returning a `BatchReport`; `each_import_batch` is the lazy equivalent. Also accepts legacy `field_names:` plus `data:`, and `overwrite_tags`, `overwrite_lists`, and `telegram_bot_channel_id`. Stops on request failures or a nonzero `invalid` count. |
+| `track_events_in_batches(events:, batch_size: 25)` | Immediate sequential event batches returning a `BatchReport`; `each_event_batch` is the lazy equivalent. Each request must also meet the 130 KiB payload limit. Batches also split automatically when the next event would exceed the byte limit. |
 | `wait_for_task(task_uuid:, interval: 1, timeout: 60)` | Polls existing tasks until completion, with a monotonic deadline. Raises on an unknown task state. Deadlines are checked between requests; an in-flight request remains bounded by transport timeouts. |
-`each_page` accepts the same operation keywords as the corresponding named method, except that `page_size` replaces `limit`. Unknown keywords, non-symbol keys, and missing or empty required values raise `ArgumentError` when enumeration starts, before any request. Direct named calls reject invalid arguments immediately. The low-level `request` method retains its existing parameter handling.
+`each_page` accepts the same operation keywords as the corresponding named method, except that `page_size` replaces `limit`. Unknown keywords, non-symbol keys, and missing or empty required values raise `ArgumentError` when the iterator is constructed, before any request. Direct named calls reject invalid arguments immediately. The low-level `request` method retains its existing parameter handling.
+Pagination additionally requires a positive integer page size within the method's documented limit, a positive integer `max_pages`, and a nonnegative integer `offset`. Named paginated reads use the same local validation for `limit` and `offset`. Each yielded response preserves its warnings and metadata.
-Pagination additionally requires a positive integer page size within the method's documented limit, a positive integer `max_pages`, and a nonnegative integer `offset`. These are helper controls; direct named calls retain the service's validation of their `limit` and `offset` values. Each yielded response preserves its warnings and metadata.
+Batch helper failures raise `BatchError`. Its `completed_responses` contains earlier successful batches, `failed_range` is the zero-based, end-exclusive input range with an uncertain or failed outcome, and `error` contains the original failure. A failed batch can still contain accepted records. Helpers do not replay batches or roll back earlier changes. Source exceptions also retain completed responses; an unknown unsent source range can be empty at the next offset.
-Batch helper failures raise `BatchError`. Its `completed_responses` contains earlier successful batches, `failed_range` is the zero-based, end-exclusive input range with an uncertain or failed outcome, and `error` contains the original failure. A failed batch can still contain accepted records. Helpers do not replay batches or roll back earlier changes.
+All batch helpers accept `retention: :full | :summary` and `on_progress:`. Full history is the default. Summary mode retains counts and failed-response details, not successful payloads. `client.with_execution(timeout:, cancellation:, instrumentation:)` creates a cooperative budget for related work. See [execution and recovery](execution.md) for checkpoint and lifetime contracts.
+## Optional workflow helpers
+| Helper | Contract |
+| --- | --- |
+| `Client.new(persistent: true)` | Reuses verified TLS connections to the marketing and Event Tracking origins. Requests on one transport are serialized. Idle connections expire after 30 seconds. A PID change discards inherited connections. Failed requests are not replayed by the transport. |
+| `client.close` | Idempotent. Rejects subsequent client requests and closes owned persistent connections. It does not close an injected transport. |
+| `RateLimiter.new(global: [count, seconds], methods: { "wireName" => [count, seconds] })` | Sliding windows apply before every marketing attempt, including retries. Share the instance to share a process-local budget. The injected `clock:` and `sleeper:` are optional. Event Tracking bypasses this limiter. |
+| `RateLimiter.unisender` | Uses the global and method-specific limits documented at the linked [request limits page](https://www.unisender.com/ru/support/api/common/api-limits/). It is opt-in and cannot account for requests from other processes. |
+| `Attachment.new(filename:, bytes:)` | Immutable binary snapshot. `from_path(path, filename:)` defaults to the basename. `from_io(io, filename:)` reads from the current position and leaves the IO open. Duplicate filenames and invalid form-field delimiters are rejected. |
+| `send_campaign(message:, campaign: {})` | Validates keyword sets and required values before either request. `message:` takes create-email options; `campaign:` takes create-campaign options except `message_id`. Returns `CampaignReceipt(message:, campaign:)`. A second-step failure raises `CampaignWorkflowError` with `message_response` and the underlying `error`. No rollback or automatic replay. |
+| `completed.download_to(io, max_bytes:, downloader: Downloader.new)` | Requires a completed task with a download URL. Returns `DownloadReceipt` with `bytes_written` and `http_status`. Never closes the IO or polls implicitly. |
+| `Downloader.new(open_timeout: 5, read_timeout: 60, write_timeout: 30)` | Separate credential-free HTTPS GET, no redirects or retries. Resolves once, rejects private or mixed public/private answers, and pins the chosen address while retaining hostname certificate verification. Downloads stream within the caller's byte limit; timeout values bound connection and IO operations, not the total transfer duration. |
+`DownloadError` exposes `reason`, `bytes_written`, and optional `http_status`. Reasons include `invalid_url`, `blocked_destination`, `http_error`, `too_large`, `incomplete`, `write_failed`, and `transport`. Signed URLs do not appear in error messages. Failed downloads can leave partial data in the caller's IO. The caller decides whether to discard or keep it. Custom downloader `resolver:` and `http_factory:` callbacks are trusted test seams and must preserve destination validation and TLS verification in production.
+Downloads conservatively reject special-use, translation, and tunneling address ranges, including NAT64 and 6to4. Ordinary global-unicast IPv6 addresses are accepted; a special-purpose prefix is not accepted merely because a local router can forward it. Address policy follows the [IANA IPv6](https://www.iana.org/assignments/iana-ipv6-special-registry/) and [IPv4](https://www.iana.org/assignments/iana-ipv4-special-registry/) registries.