# Set up or change one email connector

> Page: https://docs.plotwork.dev/api/put-orgs-org-connectors-email-provider. Index of every page: https://docs.plotwork.dev/llms.txt

Sends the organisation's email through its own provider from an address on a domain it verified, one connector a provider.

`PUT /orgs/{org}/connectors/email/{provider}`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Set up or change one email connector. |
| What does it take? | A JSON body of type [`SetOrgEmailConnectorBody`](https://docs.plotwork.dev/api/schemas.md#setorgemailconnectorbody). |
| What does it return? | Status 200 with a body of type [`OrgConnectors`](https://docs.plotwork.dev/api/schemas.md#orgconnectors). |
| What can go wrong? | `400` the body is not valid, or the token is required (`connectors.token_required`); `401` not signed in; `403` not the owner or an admin, the plan has no connectors (`plan.connectors_not_included`), or the origin may not make changes; `404` no such organisation, the caller is not a member of it, or no connector for that provider; `422` the From domain is not verified (`connectors.domain_unverified`); `429` too many requests; `503` this server cannot keep a token (`connectors.unavailable`). Every failure uses the one error envelope. |

## What it does

Sends the organisation's email through its own provider from an address on a domain it verified, one connector a provider. The token is sealed with the organisation's own data key and never answered. Enterprise only.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |
| `provider` | `"resend" \| "sendgrid" \| "postmark" \| "mailgun" \| "brevo"` | yes | The email provider: resend, sendgrid, postmark, mailgun or brevo. |

## Request body

The body has the type [`SetOrgEmailConnectorBody`](https://docs.plotwork.dev/api/schemas.md#setorgemailconnectorbody).

| Field | Type | Required | Description |
|---|---|---|---|
| `token` | `string` | no | The provider's API token. Required for a new connector; left out, the stored one is kept. at least 8 characters; at most 500 characters. |
| `fromEmail` | `string` | yes | at least 3 characters; at most 254 characters; pattern `^[^\s@]+@[^\s@]+\.[^\s@]+$`. |
| `fromName` | `string \| null` | no | at most 80 characters. |
| `replyTo` | `string \| null` | no | at least 3 characters; at most 254 characters; pattern `^[^\s@]+@[^\s@]+\.[^\s@]+$`. |
| `region` | `"us" \| "eu" \| null` | no |  |
| `enabled` | `boolean` | no |  |
| `makeDefault` | `boolean` | no | Make it the default. The organisation's first connector is the default whatever this says. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The organisation's connectors now. | [`OrgConnectors`](https://docs.plotwork.dev/api/schemas.md#orgconnectors) |
| 400 | The body is not valid, or the token is required (`connectors.token_required`). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | Not the owner or an admin, the plan has no connectors (`plan.connectors_not_included`), or the origin may not make changes. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, the caller is not a member of it, or no connector for that provider. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 422 | The From domain is not verified (`connectors.domain_unverified`). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | This server cannot keep a token (`connectors.unavailable`). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`OrgConnectors`](https://docs.plotwork.dev/api/schemas.md#orgconnectors).

| Field | Type | Required | Description |
|---|---|---|---|
| `available` | `boolean` | yes | Whether the plan has connectors: Enterprise. |
| `plan` | `string` | yes |  |
| `domains` | `string[]` | yes | The domains the organisation verified, which a From address must be on. |
| `email` | `OrgEmailConnector[]` | yes | The email connectors, at most one a provider: the default first, then in the order they were added. |
| `email[].provider` | `"resend" \| "sendgrid" \| "postmark" \| "mailgun" \| "brevo"` | yes |  |
| `email[].fromEmail` | `string` | yes |  |
| `email[].fromName` | `string \| null` | yes |  |
| `email[].replyTo` | `string \| null` | yes |  |
| `email[].region` | `"us" \| "eu" \| null` | yes | Mailgun's region; null for every other provider. |
| `email[].tokenLast4` | `string` | yes | The last four characters of the token. The token itself is never answered. |
| `email[].enabled` | `boolean` | yes |  |
| `email[].isDefault` | `boolean` | yes | Whether it is the default, the connector tried first. At most one is. |
| `email[].testedAt` | `integer \| null` | yes |  |
| `email[].lastError` | `string \| null` | yes | Why the last email through it failed, in our words, or null. |
| `email[].lastErrorAt` | `integer \| null` | yes |  |
| `email[].keyVersion` | `integer` | yes | The version of the organisation's data key the token is sealed with. |
| `email[].updatedAt` | `integer` | yes |  |
| `defaultProvider` | `"resend" \| "sendgrid" \| "postmark" \| "mailgun" \| "brevo" \| null` | yes | The provider tried first, or null when there is no connector. |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |