Organisations
Set up or change one email connector
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. |
| What does it return? | Status 200 with a body of type 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.
| 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 |
| 400 | The body is not valid, or the token is required (connectors.token_required). | ErrorResponse |
| 401 | Not signed in. | 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 |
| 404 | No such organisation, the caller is not a member of it, or no connector for that provider. | ErrorResponse |
| 422 | The From domain is not verified (connectors.domain_unverified). | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 503 | This server cannot keep a token (connectors.unavailable). | ErrorResponse |
Response body
A 200 answer has the type 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 | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |