Update and Reconnect Mailbox

PATCH https://app.mailivery.io/api/v1/campaigns/{campaignId}

This endpoint lets you modify an existing Mailivery warm‑up campaign (the mailbox connection you have already created). Use it to:

• Refresh or replace SMTP / IMAP credentials.
• Increase or decrease daily send volume and reply rate.
• Toggle the ramp‑up feature or change the mailbox’s time zone.
• Reconnect a Microsoft 365 inbox whose OAuth token has expired (special case described below).

By sending only the fields you want to change, you leave all other campaign settings untouched.

---

Two common scenarios

Scenario	How it works
Standard update	Include one or more mutable fields in the request body (e.g., emailsPerDay, smtp.password, timezone). Mailivery updates those properties and returns the full campaign object.
Microsoft re‑auth	For Microsoft 365 / Outlook campaigns created through OAuth, you can send an empty body. The endpoint responds with a fresh reconnectUrl. Redirect the user there so they can grant permissions again; Mailivery stores the new access and refresh tokens automatically.

---

Request essentials

• Method: PATCH
• Path: /campaigns/{campaignId}
• Authentication: Bearer API key

Only supply the fields you want to change; omit everything else.

---

Key request fields you might update

Field	Type	What it changes
emailsPerDay	Integer	Daily warm‑up send limit.
responseRate	Integer (0‑100)	Desired percentage of warm‑up replies.
smtp / imap objects	Object	New host, port, username, or password.
timezone	String (IANA)	The local time zone used for schedule windows.
enableRampUp	Boolean	Turn the ramp‑up algorithm on or off.
tags	Array of strings	Add or replace campaign tags.

Tip: If you need to change the warm‑up sending window, use PATCH /campaigns/{campaignId}/update-sending-schedule instead; it provides a dedicated schedule structure.

---

Success response overview

Field	Meaning
id	The campaign ID you updated.
email	Mailbox address associated with the campaign.
updatedFields	List of keys that changed in this call.
reconnectUrl	Only present when you send an empty body for a Microsoft reconnect. Redirect the user to this link.

---

Typical update flow

1. User action – They reset their SMTP password or want to raise daily volume.
2. Backend call – Your server PATCHes the campaign with the new value(s).
3. Immediate effect – Mailivery validates any credential changes and applies the new warm‑up limits within minutes.

For Microsoft reconnects, step 2 returns a reconnectUrl; send the user there to finish re‑authorising.

---

Error responses to watch for

Status	Code	What it means
400	INVALID_FIELD_VALUE	A field you supplied is out of range or mistyped (e.g., emailsPerDay : -5).
401	INVALID_API_KEY	The auth token is missing or malformed.
404	CAMPAIGN_NOT_FOUND	The campaignId does not exist or belongs to another account.
422	SMTP_IMAP_VALIDATION_FAILED	New credentials could not connect successfully. Verify host, port, username, and password.

---

When not to use this endpoint

• Starting or stopping warm‑up → use /start-warmup, /pause-warmup, /resume-warmup.
• Updating the sending schedule → use /update-sending-schedule.
• Bulk synchronising tags → use /sync-tags if you need to push an authoritative tag list.

---

Key takeaway

PATCH /campaigns/{campaignId} is the Swiss‑army knife for day‑to‑day maintenance of a Mailivery warm‑up campaign—credential refresh, volume tuning, ramp‑up toggling, and Microsoft OAuth re‑authentication all happen here with a single call.

(NOTES FOR RECONNECTING MICROSOFT MAILBOXES)

📫

Microsoft

Updating / Reconnecting Microsoft account

To reconnect Microsoft accounts hit the same endpoint without any extra parameters. You will receive the URL for user redirection.

JSON

{
    "data": {
        "url": "https://app.mailivery.io/microsoft/reconnect/eyJpdiI6IldhRi9RR0g3TkNZVGxzUkE5anNpV0E9PSIsInZhbHVlIjoiakpvU01ESWY4ZE9JYkU4ZENpNkZHQT09IiwibWFjIjoiNjI2OTc5M2UwYjQzMzA5NmVhYzMxYWEzNzNjZGM0YTY5ZDgwMGQzNGM1NmJjYjJkOWIzZWI1YmYyMTNkMTI0MyIsInRhZyI6IiJ9-hKFWe743pQMa"
    },
    "success": true,
    "status": 200,
    "code": "MICROSOFT_RECONNECT_URL_FETCHED",
    "message": "Microsoft reconnect url fetched successfully"
}