Mailocity webmail API

The signed-in user's aliases

• 200 The aliases.

  {
    "aliases": [
      "sales@acme.example"
    ],
    "canAdd": true,
    "domains": [
      "acme.example",
      "mailo.city"
    ],
    "max": 10
  }

Add an alias for the signed-in user

• 201 Added.
• 403 Not part of the plan.
• 409 Taken
• 422 Not a valid name

Remove one of the signed-in user's aliases

• 204 Removed.
• 403 Not part of the plan.
• 404 The user has no such alias.

Make an app password

{
  "currentPassword": "correct horse battery",
  "name": "Phone mail app"
}

• 201 Made.
• 403 Wrong current password
• 409 The account already has 25.
• 422 Missing or too long name.
• 429 Too many wrong passwords.

Remove an app password

• 204 Removed.
• 404 No such app password on this account.

Load a sender's BIMI logo

• 200 The logo, as image/svg+xml with a sandboxing Content-Security-Policy.
• 401 Not signed in.
• 404 No usable logo

Your calendar subscription links, and the calendars you can make one for

• 200 The links (without their addresses) and your calendars.

  {
    "calendars": [
      {
        "id": "K12",
        "name": "Work"
      }
    ],
    "items": [
      {
        "calendarId": "K12",
        "calendarName": "Work",
        "createdAt": "2026-10-08T15:00:00Z",
        "detail": "busy",
        "id": "3d0c8e52-7a41-4f7e-b6a1-0c2e9d5f8a34",
        "label": "For clients",
        "lastUsed": null
      }
    ]
  }

Make a subscription link

{
  "calendarId": "K12",
  "detail": "busy",
  "label": "For clients"
}

• 201 The link, with its address.

  {
    "calendarId": "K12",
    "calendarName": "Work",
    "createdAt": "2026-10-08T15:00:00Z",
    "detail": "busy",
    "id": "3d0c8e52-7a41-4f7e-b6a1-0c2e9d5f8a34",
    "label": "For clients",
    "lastUsed": null,
    "url": "https://mail.mailo.city/cal/cs_cal_Qm9vZ3JhZ3V0aW5nIHRoZSBjYWxlbmRhciBmZWVk.ics"
  }

• 403 In someone else's mailbox.
• 422 Not one of your calendars

Revoke a subscription link

• 204 Revoked.
• 404 You have no link with that id.

What to enter in a mail app, with the signed-in user's username

• 200 Mail app settings.

  {
    "appPassword": false,
    "autoconfigUrl": "https://mail.mailo.city/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=bob@acme.test",
    "calDav": {
      "calendarsUrl": "https://mail.mailo.city/dav/6f1c2b9e-0d4a-4c71-9a55-2d7e8f3b1a20/calendars/",
      "server": "mail.mailo.city",
      "serverUrl": "https://mail.mailo.city/.well-known/caldav",
      "username": "bob@acme.test"
    },
    "cardDav": {
      "contactsUrl": "https://mail.mailo.city/dav/6f1c2b9e-0d4a-4c71-9a55-2d7e8f3b1a20/contacts/",
      "server": "mail.mailo.city",
      "serverUrl": "https://mail.mailo.city/.well-known/carddav",
      "username": "bob@acme.test"
    },
    "imap": {
      "authentication": "Normal password",
      "host": "mail.mailo.city",
      "port": 993,
      "security": "SSL/TLS",
      "username": "bob@acme.test"
    },
    "jmap": {
      "sessionUrl": "https://mail.mailo.city/jmap/session",
      "username": "bob@acme.test",
      "webSocketUrl": "wss://mail.mailo.city/jmap/ws",
      "wellKnownUrl": "https://mail.mailo.city/.well-known/jmap"
    },
    "manageSieve": {
      "authentication": "Normal password",
      "host": "mail.mailo.city",
      "port": 4190,
      "security": "STARTTLS",
      "username": "bob@acme.test"
    },
    "smtp": {
      "authentication": "Normal password",
      "host": "mail.mailo.city",
      "port": 587,
      "security": "STARTTLS",
      "username": "bob@acme.test"
    },
    "username": "bob@acme.test"
  }

Load one remote image through the server

• 200 The image.
• 403 The link is altered or expired
• 502 The image could not be fetched or is not an allowed image.

Get links that load a message's remote images through the server

{
  "urls": [
    "https://img.example.com/logo.png"
  ]
}

• 200 Proxy links keyed by the original URL.

  {
    "links": {
      "https://img.example.com/logo.png": "/api/mail/image?a=...\u0026e=...\u0026s=...\u0026u=https%3A%2F%2Fimg.example.com%2Flogo.png"
    }
  }

• 400 Not the expected JSON
• 401 Not signed in.
• 403 Missing or wrong CSRF token.

Open a support session from a one-time link

• 201 The session.
• 400 The link was used or is more than five minutes old.
• 403 The account cannot sign in.

The user's imports from other mail servers

• 200 Newest first; fields as MailImport in api/openapi.yaml.

  {
    "items": [
      {
        "foldersDone": 1,
        "foldersTotal": 6,
        "host": "imap.example.com",
        "id": "9c1e...",
        "messagesDone": 120,
        "messagesTotal": 900,
        "status": "running",
        "username": "amy@example.com"
      }
    ]
  }

Import mail from another server over IMAP

{
  "host": "imap.gmail.com",
  "password": "app password",
  "skipFolders": [
    "[Gmail]/Spam"
  ],
  "username": "amy@gmail.com"
}

• 201 Queued.
• 409 An import is already queued or running.
• 422 A value is not valid.

Cancel a queued or running import

• 204 Cancelled; what was copied stays.
• 404 No such import.
• 409 It has already ended.

The signed-in user's invitations

• 200 The allowance and the links.

  {
    "allowance": {
      "enabled": true,
      "left": 1,
      "max": 5,
      "nextTopUp": "2026-11-06T20:17:28Z",
      "perPeriod": 2
    },
    "invitations": [
      {
        "code": "JsR4bKVKV51X3IFseJvu2g",
        "createdAt": "2026-10-07T21:17:24Z",
        "expiresAt": "2026-10-21T21:17:24Z",
        "link": "https://invite.zappo.city/?invite=JsR4bKVKV51X3IFseJvu2g",
        "note": "for dave",
        "plan": "free",
        "revokedAt": null,
        "status": "open",
        "usedAt": null,
        "usedBy": null
      }
    ]
  }

Make one invitation link

• 201 The new invitation
• 403 No invitations left

Cancel one of the user's unused links

• 204 Cancelled.
• 404 No unused invitation of the user's has that code.

The signed-in user's snoozed messages and muted conversations

• 200 Snoozes and mutes.

  {
    "muted": [
      "T17"
    ],
    "snoozed": {
      "E42": "2026-10-09T08:00:00Z"
    }
  }

The user's recent sign-ins to every service

• 200 The sign-ins.

  {
    "days": 90,
    "items": [
      {
        "at": "2026-10-08T11:59:00Z",
        "id": 7,
        "ip": "192.0.2.10",
        "login": "alice@example.com",
        "reason": "password",
        "service": "imap",
        "success": false,
        "userAgent": ""
      }
    ]
  }

Mute or unmute a conversation

{
  "muted": true,
  "threadId": "T17"
}

• 204 Changed.
• 400 Not the JSON above.
• 404 No such conversation in the user's account.

Change the signed-in user's password

• 200 Changed. Sets a new session cookie.
• 401 Not signed in.
• 403 Wrong current password
• 422 The new password is too short or too long.
• 429 Too many wrong passwords.

Ask for a password reset link

• 202 A link was sent if the account has a recovery address.
• 415 Not JSON.
• 429 Too many requests.

Set a new password from a reset link

• 200 The password is set.

  {
    "address": "alice@example.com"
  }

• 400 The link expired or was already used.
• 422 The new password is too short or too long; the link still works.

Choose what happens to the user's name+tag@ mail

{
  "mode": "refuse"
}

• 204 Saved.
• 400 Not the JSON above.
• 403 `folders` without the plus_folders entitlement.
• 422 Not one of the modes.

Set or remove the recovery address

{
  "currentPassword": "correct horse battery",
  "email": "alice.personal@example.net"
}

• 200 Removed.
• 202 Confirmation link sent.

  {
    "pending": "alice.personal@example.net",
    "recoveryEmail": null
  }

• 403 Wrong current password
• 422 Not one plain address
• 429 Too many wrong passwords
• 502 The confirmation could not be sent.

Confirm a recovery address from its link

• 200 Confirmed.

  {
    "address": "alice@example.com",
    "recoveryEmail": "alice.personal@example.net"
  }

• 400 The link expired or was already used.

Report messages as spam or phishing

{
  "emailIds": [
    "E42"
  ],
  "kind": "phishing"
}

• 200 How many were reported.

  {
    "junkId": "M4",
    "reported": 1
  }

• 400 Not the JSON above.
• 429 Too many reports today.

Two-step sign-in state and app passwords

• 200 The signed-in user's security settings.
• 401 Not signed in.
• 403 Missing or wrong CSRF token.

Which security events the user is emailed about

• 200 The choices.

  {
    "failed": true,
    "newSignin": true
  }

Choose which security events are emailed

• 204 Saved.

Send a plain-text message as a mailbox, with its API token

{
  "fromName": "Zappocity",
  "subject": "Confirm your email address",
  "text": "Open this link...",
  "to": [
    "amy@example.com"
  ]
}

• 202 Sent (or queued for other domains).

  {
    "sent": 1
  }

• 400 Not JSON with the documented fields.
• 401 No mailbox API token with the send scope
• 422 Too many recipients, a header on two lines, or the mailbox may not send this (its limits, for example).

The signed-in account and its CSRF token

• 200 Signed in.
• 401 No session

Sign in to webmail

{
  "address": "alice@example.com",
  "password": "correct horse battery"
}

• 201 Signed in. Sets the session cookie.
• 401 Wrong address or password, or the account cannot sign in. The same answer for unknown addresses. With the right password for an account with two-step sign-in, the problem has `twoFactorRequired: true`: send the request again with `code`.

  {
    "detail": "Enter the code from your authenticator app",
    "status": 401,
    "twoFactorRequired": true,
    "type": "about:blank"
  }

• 403 The password was right but the plan does not include webmail.
• 415 Not JSON.
• 429 Too many failed sign-ins.

Sign out

• 204 Signed out.
• 401 No session.
• 403 Missing or wrong CSRF token.

Where the user is signed in to webmail

• 200 The sessions.

  {
    "items": [
      {
        "createdAt": "2026-10-08T09:00:00Z",
        "current": true,
        "expiresAt": "2026-10-15T09:00:00Z",
        "id": "3f2a9c1b7d4e5f60",
        "ip": "192.0.2.10",
        "lastSeen": "2026-10-08T12:00:00Z",
        "userAgent": "Mozilla/5.0 ..."
      }
    ]
  }

Sign out one session, or every other one

• 204 Signed out.
• 404 No such session of the user.

Who the user shares their mailbox with, whose is shared with them, and their teammates

• 200 Shares and teammates.

  {
    "sharedByMe": [
      {
        "access": "send",
        "address": "assistant@acme.test",
        "name": "Sam",
        "since": "2026-10-08T15:00:00Z"
      }
    ],
    "sharedWithMe": [
      {
        "access": "read",
        "accountId": "2b7f1d6e-3c4a-4e8b-9f10-5a6b7c8d9e0f",
        "address": "sales@acme.test",
        "name": "Sales",
        "since": "2026-10-01T09:00:00Z"
      }
    ],
    "teammates": [
      {
        "address": "assistant@acme.test",
        "name": "Sam"
      },
      {
        "address": "sales@acme.test",
        "name": "Sales"
      }
    ]
  }

Share the mailbox with a teammate, or change how

{
  "access": "write"
}

• 200 The share.
• 403 Opened by someone else.
• 404 Nobody on the team has that address.
• 422 access is not read

Stop sharing the mailbox with a teammate

• 204 No longer shared.
• 404 Not shared with that teammate.

Snooze messages until a time

{
  "emailIds": [
    "E42"
  ],
  "mailboxId": "M1",
  "until": "2026-10-09T08:00:00Z"
}

• 200 Snoozed.

  {
    "mailboxId": "M7",
    "snoozedUntil": "2026-10-09T08:00:00Z"
  }

• 400 Not the JSON above.
• 422 `until` is not in the next year, or `mailboxId` is not one of the user's folders.

Bring a snoozed message back now

• 204 Back in its folder
• 404 No such message

The user's spam settings and what applies to them

• 200 The settings.

  {
    "allow": [
      "news.example"
    ],
    "block": [],
    "effectiveJunkScore": 6,
    "enabled": true,
    "junkScore": null,
    "rejectScore": 15
  }

Replace the user's own junk score and sender lists

{
  "allow": [
    "news.example"
  ],
  "block": [
    "spammy.example"
  ],
  "junkScore": 5
}

• 204 Saved.
• 400 Not the JSON above.
• 422 A list entry is not an address or domain

Which ways of signing in to webmail are open

• 200 Whether Sign in with Zappocity is offered, and whether the password sign-in still works.

  {
    "passwordSignin": true,
    "sso": true
  }

Where Zappocity sends the browser back

• 302 Signed in, to next; to /mail#sso-code when the mailbox has two-step sign-in; or to /mail#sso-error=... (expired, unverified, no-mailbox, suspended, not-in-plan).

Finish signing in with Zappocity with the mailbox's two-step code

• 201 Signed in; `session` is as from POST /api/mail/session, `next` where to go.
• 401 Wrong code (twoFactorRequired is true), or the sign-in has expired.
• 429 Too many failed attempts.

Sign in to webmail (or the team manager) with Zappocity

• 302 To Zappocity

The user's tickets

• 200 Their tickets, as Ticket in api/openapi.yaml.

  {
    "items": [
      {
        "id": 12,
        "priority": "normal",
        "queue": "team",
        "status": "pending",
        "subject": "Phone will not sync"
      }
    ],
    "teamAdmins": true
  }

Ask the team's admins or Zappocity support

• 201 The team ticket, or for Zappocity support its number and link.

  {
    "url": "https://zappo.city/account#ticket=41",
    "zappocityRef": "ZC-41"
  }

• 422 A value is missing.
• 429 Too many open tickets.

One of the user's tickets with its replies (never internal notes)

• 200 The ticket and its messages.
• 404 Not one of the user's tickets.

Close one of the user's tickets

• 204 Closed.
• 403 An abuse ticket.

Reply on a ticket; it opens again

• 204 Sent.
• 409 The ticket is closed.

Make a read tracker for a message about to be sent

• 200 The new tracker.

  {
    "token": "qOgc5Ee4_GC8gG98OT-Sew",
    "url": "https://mail.example.com/t/qOgc5Ee4_GC8gG98OT-Sew.gif"
  }

• 403 The plan does not include read tracking.
• 429 Too many trackers made today.

Get the open counts of the signed-in user's trackers

• 200 Counts keyed by token.

  {
    "trackers": {
      "qOgc5Ee4_GC8gG98OT-Sew": {
        "createdAt": "2026-10-07T20:50:30Z",
        "firstOpen": "2026-10-07T20:50:32Z",
        "lastOpen": "2026-10-07T20:50:32Z",
        "opens": 1,
        "proxiedOpens": 0,
        "token": "qOgc5Ee4_GC8gG98OT-Sew"
      }
    }
  }

• 400 Not the expected JSON

Turn two-step sign-in off

• 204 Off.
• 403 Wrong current password
• 429 Too many wrong passwords.

Turn two-step sign-in on

{
  "code": "492039"
}

• 200 On.
• 409 No setup is waiting
• 422 The code is wrong.
• 429 Too many wrong codes.

Replace the recovery codes

• 200 New codes.
• 403 Wrong current password
• 409 Two-step sign-in is off.
• 429 Too many wrong passwords.

Make a new authenticator secret

• 200 The new secret. Shown only now.
• 403 Wrong current password
• 409 Two-step sign-in is already on.
• 429 Too many wrong passwords.
• 503 The server has no key to seal secrets with.

Unsubscribe from a mailing list message

• 200 Done, or what to do instead.

  {
    "done": false,
    "mailto": "leave@list.example",
    "subject": "unsubscribe",
    "url": "https://list.example/u/123"
  }

• 404 No such message

Storage and sending used by the signed-in user

• 200 Use and limits.

  {
    "quotaBytes": 32212254720,
    "sendPerDay": 1000,
    "sentLastDay": 3,
    "storageBytes": 16179
  }

The read-tracking image

• 200 A 1x1 transparent GIF.