{ "info": { "name": "Mailyte API", "description": "The Mailyte API lets your own software do everything you can do in the Mailyte\ndashboard and webmail: send mail, manage domains and mailboxes, read delivery\nevents, run campaigns, and receive webhooks.\n\nThere are two credentials, because there are two kinds of caller.\n\nAn **organization API key** (`mk_live_…`) belongs to an organization and acts on\nits behalf — this is what your application uses. A **mailbox token** belongs to\none mailbox and acts as that person, and is what the Mailbox API takes.\n\nEvery response from the organization API is wrapped in the same envelope:\n\n```json\n{ \"message\": \"…\", \"data\": { }, \"success\": true, \"code\": 200 }\n```\n\n`data` holds the result. `success` and `code` restate the HTTP status so a client\nthat only reads the body can still tell what happened.\n\nSet the `apiKey` collection variable to your own key before sending anything.\nPath parameters are `:name` placeholders — Postman will prompt for them.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://app.mailyte.com", "type": "string" }, { "key": "apiKey", "value": "", "type": "string" } ], "item": [ { "name": "Sending", "description": "Submit messages for delivery, individually or in batches.", "item": [ { "name": "Send a message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/messages", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "messages" ] }, "body": { "mode": "raw", "raw": "{\n \"to\": [\n \"Ada Lovelace \"\n ],\n \"cc\": [\n \"accounts@acme.com\"\n ],\n \"from\": \"hello@yourdomain.com\",\n \"reply_to\": \"support@yourdomain.com\",\n \"subject\": \"Your receipt from Acme\",\n \"html\": \"

Thanks, {{first_name}}

Your order is on its way.

\",\n \"text\": \"Thanks, {{first_name}}\\nYour order is on its way.\",\n \"variables\": {\n \"first_name\": \"Ada\"\n },\n \"tags\": [\n \"receipt\"\n ],\n \"headers\": {\n \"X-Order-Id\": \"ord_1234\"\n },\n \"metadata\": {\n \"order_id\": \"ord_1234\",\n \"tier\": \"pro\"\n },\n \"attachments\": [\n {\n \"name\": \"invoice.pdf\",\n \"content\": \"JVBERi0xLjQKJ...\",\n \"content_type\": \"application/pdf\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Required scope: `messages:send`\n\nSubmits one message for delivery and returns as soon as it is accepted — delivery\nitself happens asynchronously, so a `200` here means \"queued\", not \"in their inbox\".\nWatch for the outcome through [delivery events](/developer/guides/handling-delivery-events)\nor a webhook.\n\nThree things have to be true before a send will work, and they are the cause of\nalmost every first-attempt failure:\n\n1. **The domain in `from` is verified.** See [Managing domains and DNS](/developer/guides/domains-and-dns).\n2. **`from` is a verified sender** belonging to your organization. An address that\n merely sits on a verified domain is not enough; it has to exist as a sender.\n3. **The recipient is not suppressed.** Mailyte refuses sends to addresses that have\n bounced, complained or unsubscribed, and it refuses them *before* your own list\n logic gets a say. A suppressed recipient returns `422` and records an\n `email.dropped` event.\n\nProvide content either directly (`subject` plus `html` and/or `text`) or by naming a\n`template_id`. If you do both, the fields you pass win over the template's.\n`variables` are substituted in either case." } }, { "name": "List scheduled messages", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/messages/scheduled", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "messages", "scheduled" ] }, "description": "Required scope: `messages:send`\n\nYour scheduled messages, **soonest first** — the opposite order to every other list here,\nbecause this one is about what is about to happen and newest-first would bury the next send\nunder everything already gone.\n\nBodies are not echoed back. You already have the message you scheduled, and repeating up to\n10 MB of base64 attachments in every row would make the list unusable. What comes back is\nthe envelope: to, from, subject, and what is going to happen to it." } }, { "name": "Send a batch of messages", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/messages/batch", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "messages", "batch" ] }, "body": { "mode": "raw", "raw": "{\n \"from\": \"hello@yourdomain.com\",\n \"subject\": \"Your weekly summary\",\n \"template_id\": \"01JBT8XQ2M9WYC3K4F6R7S8T9V\",\n \"messages\": [\n {\n \"to\": \"ada@example.com\",\n \"variables\": {\n \"first_name\": \"Ada\"\n }\n },\n {\n \"to\": \"grace@example.com\",\n \"variables\": {\n \"first_name\": \"Grace\"\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Required scope: `messages:send`\n\nOne shared template and a list of recipients, each with their own `variables`.\nUp to 500 recipients per call.\n\n**A partial failure is not an error.** Every recipient is processed independently, so\none suppressed or malformed address does not stop the rest — the call still returns\n`200` and the per-recipient outcome is in `results`. Check `failed` rather than the\nstatus code, or you will silently lose mail you believe you sent.\n\nThis is for transactional mail going to many people at once. For marketing sends to a\nlist or segment, use [campaigns](/developer/api/campaigns) instead: they add\nunsubscribe handling, review and reporting that this endpoint deliberately does not." } }, { "name": "Schedule a message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/messages/scheduled", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "messages", "scheduled" ] }, "body": { "mode": "raw", "raw": "{\n \"to\": [\n \"ada@example.com\"\n ],\n \"from\": \"hello@yourdomain.com\",\n \"subject\": \"Your weekly summary\",\n \"text\": \"Here is what happened this week.\",\n \"send_at\": \"2026-09-21T09:00:00Z\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Required scope: `messages:send`\n\nAccepts a message now and submits it at `send_at`. The body is exactly `POST /messages`,\nplus `send_at`.\n\n**It is a separate endpoint, and that is deliberate.** Other providers put the delivery time\non the send call, and the cost of that is a send endpoint whose response is a message on one\ncall and a schedule on the next — two object types from one operation. Here you get a\n`message` from `/messages` and a `scheduled_message` from `/messages/scheduled`, always.\n`POST /messages` **refuses** a `send_at` rather than ignoring it: a scheduling parameter\nthat is silently dropped delivers the message immediately, to everyone, at the wrong time,\nwith nothing said.\n\n**Everything that can be checked now is checked now** — the body, the recipients, the\nattachments, the limits, and that `from` is a verified Sender of yours. A scheduled send\nthat fails validation three days later is a message that silently never went, and you find\nout from the recipient.\n\n**Suppression and rate limits are checked when it leaves, not when you schedule it.** They\nare questions about the world at the moment of delivery: somebody who unsubscribes on\nTuesday must not receive a message you scheduled on Monday. When that happens the row ends\n`failed` with `failure_reason` set, so it says what happened rather than disappearing.\n\n`send_at` must be at least 60 seconds ahead — the sweep runs every minute and we will not\npromise a precision we do not have — and at most 30 days, because the whole message,\nattachments included, is stored here until it goes." } }, { "name": "Retrieve a message", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/messages/scheduled/:scheduled", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "messages", "scheduled", ":scheduled" ] }, "description": "Required scope: `messages:send`" } }, { "name": "Cancel a scheduled message", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/messages/scheduled/:scheduled", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "messages", "scheduled", ":scheduled" ] }, "description": "Required scope: `messages:send`\n\nStops a message that has not been sent.\n\n**Only while its status is `scheduled`.** Once the sweep has claimed it — status `sending` —\nthe message may already be on the wire, and there is no such thing as unsending. The cancel\nis then refused with a message naming the state it is actually in and, for one already sent,\nwhen it went. A success you could not act on would be worse than a refusal.\n\nThe cancel and the sweep are the same conditional update on one row, so exactly one of them\ncan win. You are never told a message was cancelled when it was not." } }, { "name": "Retrieve a stored message", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/messages/:messageId", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "messages", ":messageId" ] }, "description": "Required scope: `events:read`\n\nThe archived copy of a message, which is what a webhook's `storage.url` points at.\n\n`messageId` is the id **exactly as it arrived**, angle brackets included. Stripping\nthem returns `404`: the archive stores the id as it was received, and a bridge that\nhelpfully removed `<` and `>` is why every inbound message 404'd here until\n2026-09-14." } } ] }, { "name": "Templates", "description": "Stored templates with variables, rendered at send time.", "item": [ { "name": "List templates", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-templates", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-templates" ] }, "description": "Required scope: `templates:read`\n\nEvery stored template in your organization, newest first." } }, { "name": "Create a email template", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-templates", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-templates" ] }, "description": "Required scope: `templates:write`" } }, { "name": "Retrieve a email template", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-templates/:email_template", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-templates", ":email_template" ] }, "description": "Required scope: `templates:read`" } }, { "name": "Preview a rendered template", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-templates/preview", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-templates", "preview" ] }, "description": "Required scope: `templates:read`\n\nRenders a template with the variables you supply and returns the result without\nsending anything. Worth calling in your own test suite: it is the cheapest way to\ncatch a variable you renamed on one side and not the other." } }, { "name": "Update a email template", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-templates/:email_template", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-templates", ":email_template" ] }, "description": "Required scope: `templates:write`" } }, { "name": "Update a email template", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-templates/:email_template", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-templates", ":email_template" ] }, "description": "Required scope: `templates:write`" } }, { "name": "Delete a email template", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-templates/:email_template", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-templates", ":email_template" ] }, "description": "Required scope: `templates:write`" } } ] }, { "name": "Domains", "description": "Add a sending domain, publish its DNS, and verify it.", "item": [ { "name": "List domains", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Add a domain", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains" ] }, "description": "Required scope: `domains:write`\n\nRegisters a domain and returns the DNS records to publish. Nothing can be sent from it\nuntil those records are live and verification has passed.\n\nAdding a domain does **not** create any mailboxes. A domain with no mailboxes accepts\ninbound mail and then has nowhere to put it, so create at least one before pointing MX\nat us." } }, { "name": "Retrieve a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Stats (domain)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/stats", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", "stats" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Bulk Delete (domain)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/bulk-delete", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", "bulk-delete" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Bulk Update (domain)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/bulk-update", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", "bulk-update" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Bulk Verify (domain)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/bulk-verify", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", "bulk-verify" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Update a domain", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Update a domain", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Delete a domain", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Analytics a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/analytics", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "analytics" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Dkim a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/dkim", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "dkim" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Dns Provider a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/dns-provider", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "dns-provider" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Get the DNS records to publish", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/dns-records", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "dns-records" ] }, "description": "Required scope: `domains:read`\n\nThe records this domain needs, with their current observed state.\n\nSending needs **SPF and DKIM**; MX is only needed to *receive*. Mailyte tracks those\nseparately (`dns_verified` and `mx_verified`) precisely so a customer who sends through\nus but keeps their mailboxes elsewhere is not blocked on an MX record they must not\npublish." } }, { "name": "Health a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/health", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "health" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Limits a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/limits", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "limits" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Overview a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/overview", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "overview" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Stats a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/stats", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "stats" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Verification Status a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/verification-status", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "verification-status" ] }, "description": "Required scope: `domains:read`" } }, { "name": "Disable a domain", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/disable", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "disable" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Enable a domain", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/enable", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "enable" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Retry Provisioning a domain", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/retry-provisioning", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "retry-provisioning" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Send Records a domain", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/send-records", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "send-records" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Sync a domain", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/sync", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "sync" ] }, "description": "Required scope: `domains:write`" } }, { "name": "Verify a domain", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/verify", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "verify" ] }, "description": "Required scope: `domains:write`\n\nRe-checks this domain's DNS now rather than waiting for the scheduled sweep. Safe to\ncall repeatedly.\n\nDNS propagation is not instant and is not uniform — a record your own resolver can see\nmay not be visible to ours yet. If verification fails on a record you are certain is\npublished, wait and call again before assuming the value is wrong." } }, { "name": "Retrieve a domain", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/domains/:domain/limits/:email", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "domains", ":domain", "limits", ":email" ] }, "description": "Required scope: `domains:read`" } } ] }, { "name": "Mailboxes", "description": "Provision mailboxes, aliases and forwarding for a domain.", "item": [ { "name": "List email accounts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts" ] }, "description": "Required scope: `mailboxes:read`" } }, { "name": "Create a mailbox", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts" ] }, "description": "Required scope: `mailboxes:write`\n\nCreates a real mailbox — IMAP, SMTP and webmail — on one of your domains.\n\nThe domain must exist, but it does **not** need to be verified: you will usually want\nmailboxes in place before you cut MX over, not after. Provisioning happens on the mail\nserver and is asynchronous; a mailbox appears with a provisioning status and becomes\nusable when that completes.\n\nPasswords must be at least 12 characters. If you set a forced password change, note it\ngoverns webmail and the mobile apps only — IMAP and SMTP clients cannot present a\nchange-password prompt, so they keep working with the old password until it is changed\nelsewhere." } }, { "name": "Retrieve a email account", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:email_account", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":email_account" ] }, "description": "Required scope: `mailboxes:read`" } }, { "name": "Bulk Update (email account)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/bulk-update", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", "bulk-update" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Update a email account", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:email_account", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":email_account" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Update a email account", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:email_account", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":email_account" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Delete a email account", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:email_account", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":email_account" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Aliases a email account", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/aliases", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "aliases" ] }, "description": "Required scope: `mailboxes:read`" } }, { "name": "Forwarding Rules a email account", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/forwarding-rules", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "forwarding-rules" ] }, "description": "Required scope: `mailboxes:read`" } }, { "name": "Overview a email account", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/overview", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "overview" ] }, "description": "Required scope: `mailboxes:read`" } }, { "name": "Stats a email account", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/stats", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "stats" ] }, "description": "Required scope: `mailboxes:read`" } }, { "name": "Add an alias", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/aliases", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "aliases" ] }, "description": "Required scope: `mailboxes:write`\n\nAn additional address delivering into this mailbox. Aliases cannot be used as SMTP logins; they receive only." } }, { "name": "Forwarding Rules a email account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/forwarding-rules", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "forwarding-rules" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Generate Password a email account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/generate-password", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "generate-password" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Reset Password a email account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/reset-password", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "reset-password" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Retry Provisioning a email account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/retry-provisioning", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "retry-provisioning" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Update a email account", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/forwarding-rules/:rule", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "forwarding-rules", ":rule" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Delete a email account", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/aliases/:alias", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "aliases", ":alias" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Delete a email account", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/forwarding-rules/:rule", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "forwarding-rules", ":rule" ] }, "description": "Required scope: `mailboxes:write`" } }, { "name": "Retry Provisioning a email account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-accounts/:account/aliases/:alias/retry-provisioning", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-accounts", ":account", "aliases", ":alias", "retry-provisioning" ] }, "description": "Required scope: `mailboxes:write`" } } ] }, { "name": "Senders", "description": "Verified identities a message may be sent as.", "item": [ { "name": "List senders", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders" ] }, "description": "Required scope: `senders:read`" } }, { "name": "Add a sending identity", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders" ] }, "description": "Required scope: `senders:write`\n\nA sender is an identity you are allowed to send *as* — a name and address, like\n`Ada from Acme `.\n\nThis is not the same as a mailbox, and not the same as an SMTP credential. A mailbox\nreceives; a credential authenticates; a sender is what appears in the `From:` header.\n`POST /messages` refuses a `from` address that is not a verified sender here." } }, { "name": "Retrieve a sender", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders/:sender", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders", ":sender" ] }, "description": "Required scope: `senders:read`" } }, { "name": "Update a sender", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders/:sender", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders", ":sender" ] }, "description": "Required scope: `senders:write`" } }, { "name": "Update a sender", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders/:sender", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders", ":sender" ] }, "description": "Required scope: `senders:write`" } }, { "name": "Delete a sender", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders/:sender", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders", ":sender" ] }, "description": "Required scope: `senders:write`" } }, { "name": "Verification a sender", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders/:sender/verification", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders", ":sender", "verification" ] }, "description": "Required scope: `senders:read`" } }, { "name": "Verify a sender", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/senders/:sender/verify", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "senders", ":sender", "verify" ] }, "description": "Required scope: `senders:write`" } } ] }, { "name": "SMTP credentials", "description": "Logins for applications that relay over SMTP rather than HTTP.", "item": [ { "name": "List smtp credentials", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials" ] }, "description": "Required scope: `smtp:read`" } }, { "name": "Create an SMTP credential", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials" ] }, "description": "Required scope: `smtp:write`\n\nA username and password for relaying mail over SMTP, scoped to one domain.\n\n**The password is shown once.** It is stored only as a hash, so nobody — including\nMailyte — can read it back. If it is lost, rotate rather than recreate.\n\nUse SMTP when you have an existing application or library that speaks it. Use\n[`POST /messages`](/developer/api/sending/post-messages) when you are writing the\nintegration yourself: it gives you message ids, tags and per-message delivery events\nthat SMTP submission cannot." } }, { "name": "Update a smtp credential", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials/:credential", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials", ":credential" ] }, "description": "Required scope: `smtp:write`" } }, { "name": "Delete a smtp credential", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials/:credential", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials", ":credential" ] }, "description": "Required scope: `smtp:write`" } }, { "name": "Usage a smtp credential", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials/:credential/usage", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials", ":credential", "usage" ] }, "description": "Required scope: `smtp:read`" } }, { "name": "Enable a smtp credential", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials/:credential/enable", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials", ":credential", "enable" ] }, "description": "Required scope: `smtp:write`" } }, { "name": "Revoke a smtp credential", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials/:credential/revoke", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials", ":credential", "revoke" ] }, "description": "Required scope: `smtp:write`" } }, { "name": "Rotate a smtp credential", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials/:credential/rotate", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials", ":credential", "rotate" ] }, "description": "Required scope: `smtp:write`" } }, { "name": "Ip Allowlist a smtp credential", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/smtp-credentials/:credential/ip-allowlist", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "smtp-credentials", ":credential", "ip-allowlist" ] }, "description": "Required scope: `smtp:write`" } } ] }, { "name": "Events", "description": "What happened to a message after you submitted it.", "item": [ { "name": "List delivery events", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-logs", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-logs" ] }, "description": "Required scope: `events:read`\n\nEvery event recorded for your organization's mail: accepted, delivered, deferred,\nbounced, complained, opened, clicked, dropped.\n\nPolling this is the simple way to follow a send. Receiving\n[webhooks](/developer/webhooks) is the better one — it costs you no requests and tells\nyou sooner.\n\n**Opens and clicks are not reliable, by nature.** Open tracking depends on a remote\nimage loading, which privacy proxies fetch on the recipient's behalf and many clients\nblock entirely. Treat them as a weak signal about a population, never as proof about a\nperson." } }, { "name": "Retrieve a email log", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-logs/:event", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-logs", ":event" ] }, "description": "Required scope: `events:read`" } }, { "name": "Messages (email log)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-logs/messages", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-logs", "messages" ] }, "description": "Required scope: `events:read`" } }, { "name": "Delete a delivery event", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-logs/:event", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-logs", ":event" ] }, "description": "Required scope: `suppressions:write`\n\nRemoves an event from the log. Requires a write scope: a key issued for reporting must not be able to erase the history it reports on." } }, { "name": "Get a message timeline", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-logs/messages/:messageKey", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-logs", "messages", ":messageKey" ] }, "description": "Required scope: `events:read`\n\nEvery event for one message, oldest first — the whole story of a single send in one call." } }, { "name": "Resend a message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-logs/:event/resend", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-logs", ":event", "resend" ] }, "body": { "mode": "raw", "raw": "{\n \"to\": \"corrected@example.com\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Required scope: `messages:send`\n\nSubmits the stored copy of this message again. Requires `messages:send`, not\n`events:read` — it puts mail back on the wire.\n\nPass `to` to send it somewhere else. That is the usual reason to resend: the customer\ngave the wrong address, and reconstructing the message by hand to send it to the right\none loses whatever the original actually said.\n\nA redirected resend is not a privileged path — the new recipient is checked against\nyour suppression list and counted against your rate limit exactly like a fresh send." } } ] }, { "name": "Suppressions", "description": "Addresses Mailyte will refuse to send to, and why.", "item": [ { "name": "List suppressed addresses", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-suppressions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-suppressions" ] }, "description": "Required scope: `suppressions:read`\n\nAddresses Mailyte will refuse to send to, and why.\n\nSuppressions are enforced ahead of your own list logic — removing someone from your\ndatabase does not remove them from here, and adding them back in your database does\nnot resurrect them here. This is what keeps a hard bounce from being retried into a\nreputation problem." } }, { "name": "Create a email suppression", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-suppressions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-suppressions" ] }, "description": "Required scope: `suppressions:write`" } }, { "name": "Import (email suppression)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-suppressions/import", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-suppressions", "import" ] }, "description": "Required scope: `suppressions:write`" } }, { "name": "Remove a suppression", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/email-suppressions/:suppression", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "email-suppressions", ":suppression" ] }, "description": "Required scope: `suppressions:write`\n\nAllows sending to this address again.\n\nWorth doing only when you know why it was suppressed and that the cause is gone — a\nfixed typo, a mailbox that has been recreated. Removing a spam complaint because you\nwould rather keep sending is how a sending reputation is lost." } } ] }, { "name": "Webhooks", "description": "Receive delivery events at your own endpoint as they happen.", "item": [ { "name": "List webhooks", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks" ] }, "description": "Required scope: `webhooks:read`" } }, { "name": "Create a webhook endpoint", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks" ] }, "description": "Required scope: `webhooks:write`\n\nRegisters a URL to receive delivery events as they happen.\n\nDelivery is **at least once**, so the same event can arrive twice — key your handling\non the event id and make it idempotent. Events can also arrive out of order; a\n`delivered` before the `accepted` that preceded it is normal and not a bug.\n\nVerify the signature on every request before trusting the body. See\n[Receiving webhooks](/developer/guides/receiving-webhooks) for the full list of events\nand their payloads." } }, { "name": "Update a webhook", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:webhook", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":webhook" ] }, "description": "Required scope: `webhooks:write`" } }, { "name": "Delete a webhook", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:webhook", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":webhook" ] }, "description": "Required scope: `webhooks:write`" } }, { "name": "Toggle a webhook", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:webhook/toggle", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":webhook", "toggle" ] }, "description": "Required scope: `webhooks:write`" } } ] }, { "name": "Contacts", "description": "Contacts, lists, custom fields and segments.", "item": [ { "name": "List contact fields", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-fields", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-fields" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "List contact lists", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "List contact tags", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-tags", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-tags" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "List contacts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts" ] }, "description": "Required scope: `contacts:read`\n\nYour contacts, newest first.\n\n**For a sync, use `since_last_changed`.** It answers the only question an integration\nkeeping its own copy actually has — what moved — and turns a nightly full-list crawl into a\nrequest that usually returns nothing. The value is an ISO 8601 timestamp; remember to\nURL-encode it, because the `+` in `+00:00` means a space in a query string.\n\nA `since_last_changed` we cannot parse is IGNORED and you get everything, rather than\nnothing. The two failures are not symmetrical: a sync handed zero rows concludes it is up to\ndate and stops, and silently misses every change from then on.\n\n**Filter on `state`, not `status`.** `status` is what the contact row says; `state` is what\nthe product will actually do, and reconciles that row against your organization's\nsuppression list. A contact whose row says `subscribed` but whose address you suppressed\nanswers `state: \"suppressed\"` and will never be mailed — `?status=subscribed` used to hand\nthose back under a filter that claims to select the ones it will send to." } }, { "name": "List interest categorys", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/interest-categories", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "interest-categories" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "List segments", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/segments", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "segments" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "Create a contact field", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-fields", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-fields" ] }, "body": { "mode": "raw", "raw": "{\n \"label\": \"Company\",\n \"type\": \"text\",\n \"required\": true,\n \"help_text\": \"The organisation they work for\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Required scope: `contacts:write`\n\nDeclares one key of a contact's `fields` object: its label, its type, whether it is\nrequired, the value to fall back on and the hint to show beside it.\n\n**Declaring is optional.** A contact may carry any attribute key you write, declared or not,\nand an undeclared key works in content and in segment rules exactly the same. What a\ndeclaration adds is a label, a default at send time, a place in the field picker, and the\noption of requiring it. `declared` on the field object tells you which kind you are looking\nat.\n\n**`required` is enforced in two places and only two.** A contact being CREATED must supply\nit, and an update may not CLEAR a value that was already there. It is never checked\nretroactively, so marking a long-standing field required does not start rejecting contacts\nthat predate the decision — which is the only way anyone could safely turn it on for a live\naudience. In an import, a row with no value for a required field comes back in `errors[]`\nwith reason `missing_required_field`; the rest of the file still imports.\n\n**`default_value` does not satisfy `required`.** The default is substituted at render time\nfor a contact who has no value of their own and is never written to the contact. Accepting a\nplaceholder for a field you marked required would be the opposite of what you asked for.\n\nAn organization may hold 100 field definitions. The 101st is refused with the count and the\ncap in the message." } }, { "name": "Create a contact list", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Create a contact tag", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-tags", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-tags" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Create a contact", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Create a interest category", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/interest-categories", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "interest-categories" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Create a segment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/segments", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "segments" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Create or update a contact", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts" ] }, "body": { "mode": "raw", "raw": "{\n \"email\": \"ada@example.com\",\n \"name\": \"Ada Lovelace\",\n \"status_if_new\": \"subscribed\",\n \"attributes\": {\n \"plan\": \"pro\"\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Required scope: `contacts:write`\n\nCreates the contact if this email is new, updates it if it is not — the call to reach for\nwhen you are keeping your own database in step with ours.\n\nWithout it a sync needs a GET, a branch, and then a POST or a PATCH: three round trips, and\na race between the read and the write.\n\n**`status_if_new` is the one to understand.** It applies only when the contact is created.\nA nightly sync that sends `status: subscribed` for everybody in your CRM would resurrect\nevery unsubscribe it touched — the worst thing this API can do to you, because the person\nasked not to be mailed and then was. Send `status_if_new` to say \"subscribed as far as I\nknow\" without overriding what the contact themselves decided here; send `status` only when\nyou mean to change it.\n\nLists named in `list_ids` are added. The contact's other memberships are left alone." } }, { "name": "Retrieve a contact list", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists/:contact_list", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists", ":contact_list" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "Retrieve a contact", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/:contact", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", ":contact" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "Attribute Keys (contact)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/attribute-keys", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", "attribute-keys" ] }, "description": "Required scope: `contacts:read`" } }, { "name": "Import contacts", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/import", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", "import" ] }, "description": "Required scope: `contacts:write`\n\nBulk-create or update contacts. Existing contacts are matched on email address and updated rather than duplicated." } }, { "name": "Preview a segment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/segments/preview", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "segments", "preview" ] }, "description": "Required scope: `contacts:read`\n\nHow many contacts a set of rules currently matches, and a sample of them, without saving the\nsegment. Call this before sending to one.\n\n**Rules take one of four kinds of field:**\n\n| Kind | Fields | Example |\n|---|---|---|\n| Contact columns | `email`, `name`, `status` | `{\"field\": \"email\", \"op\": \"ends_with\", \"value\": \"@acme.com\"}` |\n| Custom fields | any key from `GET /contact-fields` | `{\"field\": \"plan\", \"op\": \"equals\", \"value\": \"pro\"}` |\n| Engagement | `opened`, `clicked`, `emailed` | `{\"field\": \"opened\", \"op\": \"within_days\", \"value\": \"90\"}` |\n| **Membership** | `tag`, `interest` | `{\"field\": \"tag\", \"op\": \"equals\", \"value\": \"vip\"}` |\n\n**`tag` matches by NAME, `interest` matches by ID.** That asymmetry is deliberate. A tag is\nwritten by name everywhere — created on first use, case-insensitively — so a rule holding a\nULID would break the moment somebody renamed it. An interest is an answer to a question the\n*contact* was asked and its name is form copy, so rewording \"Product updates\" must not\nsilently empty every segment built on it.\n\nMembership fields take `equals`, `not_equals`, `is_set` (has any) and `is_not_set` (has\nnone). Deliberately **not** `contains`: a tag is on a contact or it is not, and a substring\nmatch over a set would let `contains \"vip\"` quietly also match `vip-churn-risk`.\n\n**`not_equals` means \"does not carry it\", not \"carries something else\".** A contact with\nboth `vip` and `churn-risk` is EXCLUDED by `tag is not vip` — they carry it. A contact with\nno tags at all is included, because they do not.\n\nA rule we cannot evaluate — an unparseable number or date, a blank tag — matches **nothing**.\nWidening is the dangerous direction: it mails people who were never meant to be in the\naudience, and it does so quietly." } }, { "name": "Update a contact field", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-fields/:field", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-fields", ":field" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Update a contact list", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists/:contact_list", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists", ":contact_list" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Update a contact", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/:contact", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", ":contact" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Update a segment", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/segments/:segment", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "segments", ":segment" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Update a contact list", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists/:contact_list", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists", ":contact_list" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Update a contact", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/:contact", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", ":contact" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Delete a contact field", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-fields/:field", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-fields", ":field" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Delete a contact list", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists/:contact_list", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists", ":contact_list" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Delete a contact tag", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-tags/:tag", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-tags", ":tag" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Delete a contact", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/:contact", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", ":contact" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Delete a interest category", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/interest-categories/:category", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "interest-categories", ":category" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Delete a segment", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/segments/:segment", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "segments", ":segment" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Members a contact list", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists/:contactList/members", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists", ":contactList", "members" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Tags a contact", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/:contact/tags", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", ":contact", "tags" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Interests a contact", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contacts/:contact/interests", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contacts", ":contact", "interests" ] }, "description": "Required scope: `contacts:write`" } }, { "name": "Delete a contact list", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/contact-lists/:contactList/members/:contact", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "contact-lists", ":contactList", "members", ":contact" ] }, "description": "Required scope: `contacts:write`" } } ] }, { "name": "Campaigns", "description": "Bulk sends to a list or segment, scheduled and reported on.", "item": [ { "name": "List campaigns", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns" ] }, "description": "Required scope: `campaigns:read`" } }, { "name": "Create a campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns" ] }, "description": "Required scope: `campaigns:write`\n\nA campaign is a bulk send to a list or segment, with unsubscribe handling, reporting\nand — for organizations new to marketing sending — a review step.\n\nCreating one does not send it. Schedule or send it explicitly, and call\n`preflight` first: it checks the things that get a campaign stopped, and it is far\ncheaper to fail there than halfway through a list." } }, { "name": "Retrieve a campaign", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign" ] }, "description": "Required scope: `campaigns:read`" } }, { "name": "Update a campaign", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Update a campaign", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Delete a campaign", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Recipients a campaign", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/recipients", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "recipients" ] }, "description": "Required scope: `campaigns:read`" } }, { "name": "Report a campaign", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/report", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "report" ] }, "description": "Required scope: `campaigns:read`" } }, { "name": "Stats a campaign", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/stats", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "stats" ] }, "description": "Required scope: `campaigns:read`" } }, { "name": "Cancel a campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/cancel", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "cancel" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Pause a campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/pause", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "pause" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Preflight a campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/preflight", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "preflight" ] }, "description": "Required scope: `campaigns:read`\n\nChecks a campaign for the problems that would stop it — unverified domain, missing unsubscribe, empty audience, insufficient allowance — without sending anything." } }, { "name": "Resend a campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/resend", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "resend" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Resume a campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/resume", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "resume" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Schedule a campaign", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/schedule", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "schedule" ] }, "description": "Required scope: `campaigns:write`" } }, { "name": "Send a campaign now", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/send", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "send" ] }, "description": "Required scope: `campaigns:write`\n\nBegins the send immediately.\n\nMarketing mail rides a different egress path from transactional mail, deliberately, so\na newsletter cannot damage the reputation that carries your password resets. New\nmarketing senders are rate-limited while they warm up, so a large first campaign will\ntake longer than you expect — that is the system working." } }, { "name": "Send a test", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/campaigns/:campaign/test-send", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "campaigns", ":campaign", "test-send" ] }, "description": "Required scope: `campaigns:write`\n\nSends the campaign to addresses you name, so you can see it as a recipient would. Does not touch the audience and does not count against the campaign report." } } ] }, { "name": "Reports", "description": "Deliverability, engagement and volume reporting.", "item": [ { "name": "List deliverabilitys", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/deliverability", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "deliverability" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Domain Health (report)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/domain-health", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "domain-health" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Email Delivery (report)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/email-delivery", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "email-delivery" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Engagement (report)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/engagement", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "engagement" ] }, "description": "Required scope: `reports:read`" } }, { "name": "History (report)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/history", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "history" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Security (report)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/security", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "security" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Templates (report)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/templates", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "templates" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Volume Trends (report)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/volume-trends", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "volume-trends" ] }, "description": "Required scope: `reports:read`" } }, { "name": "Generate (report)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/reports/generate", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "reports", "generate" ] }, "description": "Required scope: `reports:read`" } } ] }, { "name": "Transport rules", "description": "Organization-wide rules applied to mail in transit.", "item": [ { "name": "List transport rules", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transport-rules", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transport-rules" ] }, "description": "Required scope: `transport_rules:read`" } }, { "name": "Create a transport rule", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transport-rules", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transport-rules" ] }, "description": "Required scope: `transport_rules:write`" } }, { "name": "Retrieve a transport rule", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transport-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transport-rules", ":id" ] }, "description": "Required scope: `transport_rules:read`" } }, { "name": "Update a transport rule", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transport-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transport-rules", ":id" ] }, "description": "Required scope: `transport_rules:write`" } }, { "name": "Reorder (transport rule)", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transport-rules/reorder", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transport-rules", "reorder" ] }, "description": "Required scope: `transport_rules:write`" } }, { "name": "Delete a transport rule", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transport-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transport-rules", ":id" ] }, "description": "Required scope: `transport_rules:write`" } }, { "name": "Enable a transport rule", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transport-rules/:id/enable", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transport-rules", ":id", "enable" ] }, "description": "Required scope: `transport_rules:write`" } } ] }, { "name": "Account", "description": "Organization usage, limits, API keys and dedicated IPs.", "item": [ { "name": "List API keys", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/api-keys", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "api-keys" ] }, "description": "Required scope: `account:read`\n\nThe keys your organization holds, with their prefixes, scopes and last use.\n\nListing is available to a key; **creating and revoking are not.** A leaked key that\ncould mint its own replacement would outlive the revocation of the key that leaked,\nso those stay in the dashboard on purpose." } }, { "name": "Get dedicated IP status", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/dedicated-ip", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "dedicated-ip" ] }, "description": "Required scope: `account:read`\n\nYour dedicated sending address and its warm-up state. An organization on a shared IP gets a populated object whose `state` is `shared` and whose `address` is null — NOT a null result, and never an error. Reachable with an organization API key carrying `account:read`; a key without that scope is refused with 403." } }, { "name": "Entitlements (billing)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/billing/entitlements", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "billing", "entitlements" ] }, "description": "Required scope: `account:read`" } }, { "name": "Send Plan (billing)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/billing/send-plan", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "billing", "send-plan" ] }, "description": "Required scope: `account:read`" } }, { "name": "Subscription (billing)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/billing/subscription", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "billing", "subscription" ] }, "description": "Required scope: `account:read`" } }, { "name": "Get current usage", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/billing/usage", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "billing", "usage" ] }, "description": "Required scope: `account:read`\n\nWhat your organization has sent this period, against its plan allowance and any purchased credits." } } ] }, { "name": "Mailbox API", "description": "Everything the webmail does, for one mailbox. Takes a mailbox token, not an organization API key.", "item": [ { "name": "Senders this mailbox has blocked", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/blocked-senders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "blocked-senders" ] }, "description": "Mail from a blocked address is filed to the Junk folder at delivery, before any rule, forward or vacation reply runs. Nothing is discarded." } }, { "name": "Subscription links for this mailbox", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendar-subscriptions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendar-subscriptions" ] }, "description": "" } }, { "name": "Calendars in this mailbox", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendars", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendars" ] }, "description": "" } }, { "name": "What this deployment's webmail can actually do", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/capabilities", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "capabilities" ] }, "description": "Runtime feature detection for the webmail: which optional services are configured on THIS deployment. Distinct from /api/v1/capabilities, which reports the build's edition (CE vs Pro) and cannot answer questions like 'is an AI endpoint configured', since two deployments of the same edition differ. The webmail hides any control this does not advertise." } }, { "name": "Addresses this mailbox has written to", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/contacts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "contacts" ] }, "description": "Harvested from the Sent folder, most-used first, for compose autocomplete. People WRITTEN TO only -- senders of received mail are deliberately excluded, or every cold email and newsletter in the inbox would become a suggestion. Colleagues nobody has written to yet come from the company directory instead." } }, { "name": "List the mailbox's folders", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/folders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "folders" ] }, "description": "Every folder with its message and unread counts plus IMAP's UIDNEXT and UIDVALIDITY. Polling those two is the webmail's delta check: unchanged tokens mean nothing arrived, moved or was deleted, for one request that transfers no messages." } }, { "name": "Mail forwarding settings", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/forwarding", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "forwarding" ] }, "description": "" } }, { "name": "The mailbox's own analytics", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/insights", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "insights" ] }, "description": "Server-side aggregation over this mailbox's INBOX, Sent and Drafts headers: attention backlog, response times, weekly rhythm, relationships and hygiene, threaded by RFC 5322 identifiers. Every top-level block is independent -- a block that cannot be computed is omitted, and the client hides that section. Results are cached per window; window.to is the compute time. `refresh=true` recomputes, rate-limited per mailbox; when throttled, the cached copy is served." } }, { "name": "List messages in a folder", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages" ] }, "description": "Newest first, server-side searched and paged. `q` is resolved by IMAP SEARCH against Dovecot's own indexes -- including message bodies -- so a word buried deep in an email is findable, which a client-side search over preview text can never be." } }, { "name": "The mailbox's filter rules", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/rules", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "rules" ] }, "description": "" } }, { "name": "The mailbox holder's security state", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/security", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "security" ] }, "description": "Two-factor status and what it protects. `protects` is part of the contract: mailbox 2FA gates the webmail sign-in only, never IMAP or SMTP, and the UI must not overclaim its reach." } }, { "name": "The mailbox holder's own settings", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/settings", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "settings" ] }, "description": "Signature, display density, undo-send and real storage figures." } }, { "name": "The vacation responder", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/vacation", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "vacation" ] }, "description": "" } }, { "name": "Sign in to the webmail with mailbox credentials", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox-auth/login", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox-auth", "login" ] }, "description": "Exchanges a mailbox's own email and password for a webmail session. The password is verified by IMAP LOGIN against Dovecot, never against a stored copy, so this can never disagree with what a mail client would accept. Unauthenticated by design, rate-limited by IP and by address. Send `X-Client-Platform: ios|android|macos|windows|linux` from a native app to receive the native session lifetimes (default 30 days idle / 180 days absolute) instead of the browser's 8 hours / 7 days. If the account carries a temporary password the session is still issued, `data.must_change_password` is true, and every /api/v1/mailbox/* route except POST /security/password and logout answers 403 `password_change_required` until a new password is set." } }, { "name": "End the current webmail session", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox-auth/logout", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox-auth", "logout" ] }, "description": "Revokes the session server-side and clears its cookies. Idempotent." } }, { "name": "Block a sender", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/blocked-senders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "blocked-senders" ] }, "description": "Adds one address. Matching is on the visible From address, whole address, case-insensitive. Blocking an address that is already blocked is not an error." } }, { "name": "Create a subscription link", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendar-subscriptions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendar-subscriptions" ] }, "description": "" } }, { "name": "Create a folder", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/folders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "folders" ] }, "description": "Creates and subscribes an IMAP folder. This is also what the webmail's label management calls -- a label IS a folder here, not a separate concept invented in the UI." } }, { "name": "Update mail forwarding", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/forwarding", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "forwarding" ] }, "description": "Backed by Sieve `redirect :copy`, not a Postfix alias -- the alias route delivers two copies of every forwarded message." } }, { "name": "Replace the mailbox's filter rules", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/rules", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "rules" ] }, "description": "" } }, { "name": "Update the mailbox holder's settings", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/settings", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "settings" ] }, "description": "Partial update -- only the fields present are changed. The signature is sanitised against an allowlist before storage, because it is HTML this server later attaches to outgoing mail." } }, { "name": "Update the vacation responder", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/vacation", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "vacation" ] }, "description": "Replies at most once per sender per day, and only to mail actually addressed to this mailbox -- a message merely Cc'd to a list does not trigger one." } }, { "name": "Address books this mailbox can see", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/address-book/books", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "address-book", "books" ] }, "description": "The personal collection, plus anything shared with the mailbox.\n\n`read_only` is reported off the server's own privilege set rather than\nguessed from the name, so a UI can hide editing controls on a collection\nthe server would refuse to write anyway -- the company directory being the\ncase that matters." } }, { "name": "Saved contacts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/address-book/contacts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "address-book", "contacts" ] }, "description": "" } }, { "name": "The mailbox holder's AI consent state", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/consent", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "consent" ] }, "description": "Current opt-in flags, the version accepted, when, the version currently in force, and the URL of the consent document. Deliberately available regardless of entitlement or org policy -- reading one's own consent state is never gated." } }, { "name": "The current AI assistant terms", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/terms", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "terms" ] }, "description": "The full text of the terms the holder would be accepting, with its version and SHA-256. The client shows this text before POST /ai/consent; consent to one version is never consent to the next." } }, { "name": "Invitations awaiting an answer", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendar/invitations", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendar", "invitations" ] }, "description": "What is in this mailbox's scheduling inbox.\n\nThe same collection Apple Calendar and DAVx5 read, so answering here and\nanswering on a phone cannot disagree about what is still outstanding." } }, { "name": "Rooms and equipment you can invite", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendar/rooms", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendar", "rooms" ] }, "description": "The bookable rooms in this mailbox's own organisation.\n\nThis exists so that somebody making a meeting can PICK a room rather than\nknow its address by heart. Without it the address is the only handle a\nperson has, and an address typed from memory is a booking that silently\ngoes nowhere -- which is most of the reason rooms went unused.\n\nRead-only and mailbox-scoped on purpose. Creating a room is an admin\ndecision and stays on /calendar-resources behind an API key; seeing what\nyou may invite is not. The exposure is the same shape as free/busy --\nyour own organisation's directory, nobody else's -- so it is bounded the\nsame way, by organization_id and nothing the caller can supply.\n\nInactive rooms are omitted rather than shown greyed out: a room switched\noff is one nobody should be trying to book, and offering it only produces\nan invitation that is never answered." } }, { "name": "Read one message", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id" ] }, "description": "The full message with both body representations and attachment metadata. Fetched with BODY.PEEK, so opening a message does not mark it read -- the client says so explicitly via /mark-read, which is what makes 'mark as unread' mean anything." } }, { "name": "Messages waiting to be sent", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/scheduled", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", "scheduled" ] }, "description": "Send times for everything in the Scheduled folder, keyed by the same message id the folder listing returns, so a client merges the two rather than fetching the messages twice. Includes any that FAILED: a scheduled message that did not go out is the one the holder most needs to see." } }, { "name": "Where this mailbox is signed in", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/security/sessions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "security", "sessions" ] }, "description": "" } }, { "name": "Save a contact", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/address-book/contacts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "address-book", "contacts" ] }, "description": "" } }, { "name": "Label a batch of messages", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/classify", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "classify" ] }, "description": "Classifies up to 20 messages by subject and preview into a closed label vocabulary with a confidence per item. One batch costs one call against the monthly allowance; the response carries ai_calls_remaining." } }, { "name": "Draft or rewrite a message with AI", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/compose", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "compose" ] }, "description": "503 error_code ai_not_configured when no endpoint is set; 403 org_policy_blocked / not_entitled / consent_required / terms_version_stale when a Maya gate fails; 429 ai_quota_exhausted when the monthly allowance is spent. Responses carry ai_calls_remaining." } }, { "name": "Accept the AI assistant terms", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/consent", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "consent" ] }, "description": "Records the holder's acceptance of the CURRENT terms version -- 409 with error_code terms_version_stale if the submitted version is not current, so a client holding yesterday's text can never bind the holder to words they did not see. On success the acceptance is written to an append-only ledger together with a sealed PDF record (mailbox, both decisions, the full terms text as agreed, timestamp, actor), and the response carries its consent_id and document_url." } }, { "name": "When are these people busy", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendar/free-busy", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendar", "free-busy" ] }, "description": "Busy periods for each address, within the caller's own organization.\n\nTwo limits worth knowing, both reported rather than hidden:\n\n* A colleague at another company always comes back `known: false`. Neither\n Google nor Microsoft exposes free/busy to strangers, so there is no\n answer to give -- and showing an unknown person as free would invent one.\n* The attendee list is capped. This is an organization directory oracle:\n unbounded, it is a way to enumerate who exists and when they work." } }, { "name": "Save a draft", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/draft", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", "draft" ] }, "description": "Appends the draft to the Drafts folder as a real message, so it is readable by every other client on the account rather than living in a webmail-only table." } }, { "name": "Send a message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/send", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", "send" ] }, "description": "Submits through Postfix and files a copy in Sent. The From address is always the signed-in mailbox: submission is trusted-network rather than SASL-authenticated, so Postfix's own sender-login check is bypassed and this endpoint is the only thing preventing one mailbox sending as another. Replies (`in_reply_to` set) flag the original \\Answered; forwards carry attachments over with `forward_attachments_from` + `attachment_indexes`. With `send_at` (ISO-8601) the message is stored in the Scheduled folder and sent at that time instead -- the response then carries `send_at` and the id it can be cancelled by." } }, { "name": "Change this mailbox's password", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/security/password", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "security", "password" ] }, "description": "Verifies `current_password` by IMAP LOGIN against Dovecot (the same check sign-in uses), enforces the platform password policy on `new_password`, stores the new bcrypt hash, flushes Dovecot's auth cache so IMAP/SMTP honour the change immediately, and signs out every OTHER session of this mailbox. The calling session stays signed in. Clears a pending forced change (`must_change_password`), so this is the one route a session carrying a temporary password may call besides sign-out. Failed `current_password` attempts count against the same lockout as sign-in." } }, { "name": "Rename a folder", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/folders/:folder", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "folders", ":folder" ] }, "description": "`folder` is the id GET /folders returns. `name` is the new last segment; a nested folder keeps its parent, and RENAME carries its subfolders along. INBOX and the special-use folders (Sent, Drafts, Junk, Trash, Archive -- detected by SPECIAL-USE attribute and by well-known name) answer 409 `cannot_rename_special_folder`." } }, { "name": "Withdraw AI consent entirely", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/consent", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "consent" ] }, "description": "Withdraws both the assistant and training decisions and writes a 'revoked' ledger entry with its own receipt document. Idempotent: with nothing to withdraw it succeeds without writing anything." } }, { "name": "Unblock a sender", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/blocked-senders/:address", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "blocked-senders", ":address" ] }, "description": "Removes one address. Unblocking an address that is not blocked is not an error. Mail already filed to Junk stays where it is." } }, { "name": "Revoke a subscription link", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendar-subscriptions/:token", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendar-subscriptions", ":token" ] }, "description": "" } }, { "name": "Delete an empty folder", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/folders/:folder", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "folders", ":folder" ] }, "description": "`folder` is the id GET /folders returns. Refused with 409 `cannot_delete_special_folder` for INBOX and the special-use folders, and with 409 `folder_not_empty` (messages) or `folder_has_subfolders` while anything is still inside -- IMAP DELETE destroys contents without a Trash step, so the holder empties the folder deliberately first. The client should warn on 409 rather than retry." } }, { "name": "Permanently delete a message", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id" ] }, "description": "Refused unless the message is ALREADY in Trash. PRD section 7 is binding: nothing outside Trash is ever destroyed, so reaching this requires a deliberate second delete from inside Trash." } }, { "name": "One contact", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/address-book/contacts/:card_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "address-book", "contacts", ":card_id" ] }, "description": "" } }, { "name": "The mailbox holder's consent history", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/consent/history", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "consent", "history" ] }, "description": "Every acceptance and withdrawal, newest first, including any revoked_by_organisation entries written when an org admin set the AI policy to blocked. Each entry links its stored document." } }, { "name": "Events overlapping a time range", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendars/:calendar/events", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendars", ":calendar", "events" ] }, "description": "" } }, { "name": "List a message's attachments", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/attachments", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "attachments" ] }, "description": "" } }, { "name": "Who this message is with, and the shape of its conversation", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/context", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "context" ] }, "description": "Header-only context for one message: the history with its correspondent and the thread it belongs to. Always available -- no AI is involved and none is required. A message with no identifiable correspondent (a bounce, a self-note) omits the correspondent block." } }, { "name": "Download the original message (RFC 822)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/raw", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "raw" ] }, "description": "The stored bytes exactly as Dovecot holds them -- headers, MIME structure and encodings untouched, never a re-serialisation. What 'Show original' and 'Download .eml' load, and the ground truth for any 'is the API dropping this header?' question. Fetched with BODY.PEEK, so it does not mark the message read." } }, { "name": "The conversation a message belongs to", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/thread", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "thread" ] }, "description": "Oldest first. Threading follows RFC 5322 Message-ID / In-Reply-To / References, never subject lines -- subject matching collapses unrelated 'Re: hello' messages into one conversation." } }, { "name": "Summarise a message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/summarize/:message_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "summarize", ":message_id" ] }, "description": "Gated and metered exactly like /ai/compose. The whole-conversation variant is POST /ai/summarize/thread/{message_id} (routes/mailbox_ai.py)." } }, { "name": "Create an event", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendars/:calendar/events", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendars", ":calendar", "events" ] }, "description": "" } }, { "name": "Mark a message read", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/mark-read", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "mark-read" ] }, "description": "" } }, { "name": "Mark a message unread", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/mark-unread", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "mark-unread" ] }, "description": "" } }, { "name": "Move a message to another folder", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/move", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "move" ] }, "description": "" } }, { "name": "Star a message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/star", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "star" ] }, "description": "" } }, { "name": "Move a message to Trash", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/trash", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "trash" ] }, "description": "What the webmail's delete button calls. Recoverable by design." } }, { "name": "Unstar a message", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/unstar", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "unstar" ] }, "description": "" } }, { "name": "Start two-factor enrolment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/security/2fa/begin", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "security", "2fa", "begin" ] }, "description": "Generates a secret and recovery codes. Enrolment is NOT active until /confirm succeeds with a working code -- otherwise a mis-scanned QR would lock the holder out of their own mailbox." } }, { "name": "Confirm two-factor enrolment with a code", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/security/2fa/confirm", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "security", "2fa", "confirm" ] }, "description": "" } }, { "name": "Turn two-factor off", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/security/2fa/disable", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "security", "2fa", "disable" ] }, "description": "Requires a current code, so a borrowed session cannot remove it." } }, { "name": "Replace a contact", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/address-book/contacts/:card_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "address-book", "contacts", ":card_id" ] }, "description": "`etag` is the copy the caller last read.\n\nWithout it, two devices editing the same contact end with one silently\noverwriting the other. With it the second write is refused and the client\ncan re-read -- the same contract the calendar's event update uses." } }, { "name": "Delete a contact", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/address-book/contacts/:card_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "address-book", "contacts", ":card_id" ] }, "description": "" } }, { "name": "Withdraw the training decision only", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/consent/training", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "consent", "training" ] }, "description": "Turns off use of this mailbox's requests for model improvement while leaving the assistant itself consented. Idempotent." } }, { "name": "Discard a draft", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/draft/:message_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", "draft", ":message_id" ] }, "description": "Permanently removes a draft. Allowed outside Trash because a draft the author just discarded was never delivered mail." } }, { "name": "Cancel a scheduled send", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/scheduled/:message_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", "scheduled", ":message_id" ] }, "description": "Moves the message back to Drafts and forgets the schedule. The message is never destroyed -- someone cancelling a send wants to change it, not lose it." } }, { "name": "Sign out another device", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/security/sessions/:session_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "security", "sessions", ":session_id" ] }, "description": "Revokes one session. Refuses the caller's own -- signing yourself out from a list of other devices is almost always a misclick, and /logout is the deliberate way to do it." } }, { "name": "Download one consent document", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/consent/:consent_id/document", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "consent", ":consent_id", "document" ] }, "description": "The stored PDF for one ledger entry -- own records only; another mailbox's id is a 404, not a 403." } }, { "name": "One event", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendars/:calendar/events/:event_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendars", ":calendar", "events", ":event_id" ] }, "description": "" } }, { "name": "Download one attachment", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/messages/:message_id/attachments/:index", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "messages", ":message_id", "attachments", ":index" ] }, "description": "Streams the decoded part back with its own content type and filename." } }, { "name": "Summarise a whole conversation", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/ai/summarize/thread/:message_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "ai", "summarize", "thread", ":message_id" ] }, "description": "Follows the message's RFC 5322 thread (shared/imap_mail.thread_for, read-only), stitches the most recent messages into one prompt, and summarises the conversation. Gated like every Maya endpoint; the response carries ai_calls_remaining." } }, { "name": "Answer an invitation", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendar/invitations/:invitation_id/rsvp", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendar", "invitations", ":invitation_id", "rsvp" ] }, "description": "Accept, decline or tentatively accept.\n\nThe RFC 6638 dance, in order, and the order is what makes it work:\n\n 1. Read the message out of the scheduling inbox.\n 2. Set this mailbox's PARTSTAT on it, changing nothing else.\n 3. PUT it into the user's own calendar. **This is what sends the REPLY**\n -- the scheduling plugin sees an attendee copy whose PARTSTAT\n changed and generates the iTIP REPLY to the organizer. Nothing here\n constructs that message by hand.\n 4. Remove the message from the scheduling inbox, which is the client's\n job under RFC 6638. Skipping it leaves the invitation showing as\n unanswered in every native client forever.\n\nStep 4 is deliberately best-effort: if it fails, the answer has already\nbeen sent and recorded, and failing the whole call would invite the user\nto answer twice." } }, { "name": "Replace an event", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendars/:calendar/events/:event_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendars", ":calendar", "events", ":event_id" ] }, "description": "" } }, { "name": "Delete an event", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/mailbox/calendars/:calendar/events/:event_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "mailbox", "calendars", ":calendar", "events", ":event_id" ] }, "description": "" } } ] } ] }