Mailboxes

Update mailbox

Updates mailbox tag assignments and the mailbox ESP filter. Mailbox profile and credential fields remain read-only on the Client API.

recipient_esps sets which email providers this mailbox sends first emails to, in every campaign that uses it. It applies only to a lead's first email. Follow-ups and replies always use the mailbox that sent the first email.

The response carries warnings next to data. When the new filter leaves an unfinished campaign with no mailbox for some of its leads, a warning names those campaigns. The update is saved either way.

PATCH/v1/mailboxes/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

Use an account API key in the Authorization header: Authorization: Bearer f_....

In: header

Path Parameters

idstring

Mailbox id.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tag_ids?array<string>

Replace all tag assignments on the mailbox.

add_tag_ids?array<string>

remove_tag_ids?array<string>

recipient_esps?array<string>

ESP filter: the email providers this mailbox sends first emails to, in every campaign that uses it. Omit to leave it unchanged. Send one or more of google, microsoft and other, each at most once. other is every provider that is not Google or Microsoft. All three and null both mean every provider. An empty list is rejected. A mailbox filter always wins over a campaign's auto_esp_match. The filter applies only to a lead's first email. Follow-ups and replies always use the mailbox that sent the first email. When a filter applies, a lead whose email provider has not been checked yet waits for the check, usually about a minute.

Items1 <= items

curl -X PATCH "https://example.com/v1/mailboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "recipient_esps": [      "microsoft",      "other"    ]  }'

{  "data": {    "id": "c23da7b6-df4e-4d2f-b100-4bb07b7d38d7",    "sending_esp": "other",    "recipient_esps": [      "microsoft",      "other"    ],    "tags": []  },  "warnings": [    {      "code": "esp_mailbox_filter_affects_campaigns",      "severity": "warning",      "message": "1 campaign will stop reaching some leads: Q2 Pipeline (Gmail).",      "affected_campaigns": [        {          "id": "1d8dc901-3d2d-4d9f-9dcc-4f8b3aa1a1fb",          "name": "Q2 Pipeline"        }      ]    }  ]}

{  "error": {    "type": "invalid_request_error",    "code": "invalid_flow",    "message": "Flow validation failed"  },  "details": [    {      "path": "nodes[1].data.variants[0].id",      "code": "invalid_variant_id",      "message": "Email variants must have a stable UUID id."    }  ]}

{  "error": {    "type": "authentication_error",    "code": "invalid_api_key",    "message": "A valid Furnace API key is required"  }}

{  "error": {    "type": "invalid_request_error",    "code": "campaign_not_found",    "message": "Campaign not found"  }}

{  "error": {    "type": "rate_limit_error",    "code": "rate_limit_exceeded",    "message": "Rate limit exceeded for this account"  }}

{  "error": {    "type": "api_error",    "code": "internal_error",    "message": "Internal server error"  }}