API Reference/Accounts/Connect an account (hosted authentication)

Connect an account (hosted authentication)

POSThttps://api.postpress.ai/v1/hosted/accounts/link

Create a single-use URL that redirects the user to postpress' hosted authentication flow. Use this to connect a new account or to reconnect an existing one without handling provider credentials yourself.

Authorization

X-API-KEYstringrequired
API key from your postpress dashboard. Sent as a request header.

Request body

The body is one of two variants, selected by the type field.

Connection linkobject
Use this shape to generate a link for connecting a brand-new account (`type: "create"`).
Connection link object
typestringcreaterequired
Use `create` to generate a link for connecting a new account.
providersstring or array of stringsrequired
The providers offered in the hosted authentication interface. Use a single wildcard string (`*`, `*:MAILING`, `*:MESSAGING`, `*:CALENDAR`), or an array of specific provider tags.
providers object
<wildcard>string
**:MAILING*:MESSAGING*:CALENDAR
Single-string form. `*` accepts any provider, the suffix variants restrict to a domain.
<providers[]>array of strings
Array form. One or more specific provider tags.
<providers[]> array
<provider>string
LINKEDINWHATSAPPINSTAGRAMMESSENGERTELEGRAMGOOGLEOUTLOOKTWITTERMAIL
expiresOnstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). Note: all links expire on the daily restart, regardless of this value. Generate a new link each time a user starts the flow.
Example: 2026-12-31T23:59:59.999Z
api_urlstringrequired
The url of your postpress API server, e.g. https://api.postpress.ai.
namestringlength ≥ 1
Echoed back to your notify_url so you can match the created account with your end user.
success_redirect_urlstring
Where to redirect the user after a successful authentication.
failure_redirect_urlstring
Where to redirect the user after a failed authentication.
bypass_success_screenboolean
When true, skip the hosted-auth success screen and go directly to success_redirect_url.
notify_urlstring
Webhook url that receives events about the authentication process.
disabled_featuresarray of strings
Features to disable on the resulting account.
disabled_features array
<feature>string
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
disabled_optionsarray of strings
Options to hide in the hosted auth interface. `qrcode_auth` and `pairing_code_auth` are currently supported for WhatsApp only.
disabled_options array
<option>string
proxyautoproxycookie_authcredentials_authqrcode_authpairing_code_authsync_limitlanguage
proxyobject
Optional proxy to attach to the resulting account.
proxy object
hoststringrequired
portnumberrequired
protocolstring
httpshttpsocks5
usernamestring
Optional username for proxy authentication.
passwordstring
Optional password for proxy authentication.
sync_limitobject
Per-domain sync limits to apply at first sync.
sync_limit object
MAILINGstringNO_HISTORY_SYNC
Disables historical mail sync.
MESSAGINGobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Provider support is partial.
MESSAGING object
chatsstring or number
ISO 8601 UTC datetime to start sync from, or a number of items (0 disables history sync).
messagesstring or number
ISO 8601 UTC datetime to start sync from, or a number of items (0 disables history sync).
google_scopesstring
Optional comma-separated list of OAuth scopes for GOOGLE_OAUTH accounts.
microsoft_scopesstring
Optional comma-separated list of OAuth scopes for OUTLOOK accounts.
Reconnection linkobject
Use this shape to generate a link for re-authenticating an existing account (`type: "reconnect"`).
Reconnection link object
typestringreconnectrequired
Use `reconnect` to generate a link for re-authenticating an existing account.
reconnect_accountstringlength ≥ 1required
The id of the account to reconnect.
expiresOnstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). Note: all links expire on the daily restart, regardless of this value. Generate a new link each time a user starts the flow.
Example: 2026-12-31T23:59:59.999Z
api_urlstringrequired
The url of your postpress API server, e.g. https://api.postpress.ai.
namestringlength ≥ 1
Echoed back to your notify_url so you can match the created account with your end user.
success_redirect_urlstring
Where to redirect the user after a successful authentication.
failure_redirect_urlstring
Where to redirect the user after a failed authentication.
bypass_success_screenboolean
When true, skip the hosted-auth success screen and go directly to success_redirect_url.
notify_urlstring
Webhook url that receives events about the authentication process.
disabled_featuresarray of strings
Features to disable on the resulting account.
disabled_features array
<feature>string
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
disabled_optionsarray of strings
Options to hide in the hosted auth interface. `qrcode_auth` and `pairing_code_auth` are currently supported for WhatsApp only.
disabled_options array
<option>string
proxyautoproxycookie_authcredentials_authqrcode_authpairing_code_authsync_limitlanguage
proxyobject
Optional proxy to attach to the resulting account.
proxy object
hoststringrequired
portnumberrequired
protocolstring
httpshttpsocks5
usernamestring
Optional username for proxy authentication.
passwordstring
Optional password for proxy authentication.
sync_limitobject
Per-domain sync limits to apply at first sync.
sync_limit object
MAILINGstringNO_HISTORY_SYNC
Disables historical mail sync.
MESSAGINGobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Provider support is partial.
MESSAGING object
chatsstring or number
ISO 8601 UTC datetime to start sync from, or a number of items (0 disables history sync).
messagesstring or number
ISO 8601 UTC datetime to start sync from, or a number of items (0 disables history sync).
google_scopesstring
Optional comma-separated list of OAuth scopes for GOOGLE_OAUTH accounts.
microsoft_scopesstring
Optional comma-separated list of OAuth scopes for OUTLOOK accounts.

Response 200 OK

objectstringHostedAuthUrlrequired
urlstringrequired
The single-use URL redirecting the user to postpress' hosted authentication.

Example request

{
  "type": "create",
  "providers": "*",
  "api_url": "https://api.postpress.ai",
  "expiresOn": "2026-12-31T23:59:59.999Z",
  "success_redirect_url": "https://yourapp.com/connected"
}

Example response

{
  "object": "HostedAuthUrl",
  "url": "https://api.postpress.ai/hosted/auth/abc123def456..."
}

Errors

Every error response follows the same envelope:

titlestringrequired
Short error title.
detailstringoptional
Human-readable explanation.
instancestringoptional
Request identifier for support.
typestringrequired
Error type identifier, e.g. `errors/invalid_parameters`.
statusnumberrequired
HTTP status code.
400 Bad Request8 types

The request payload is invalid or missing required fields.

  • errors/invalid_parameters - One or more request parameters are invalid or missing.
  • errors/missing_parameters - One or more request parameters are missing.
  • errors/invalid_request - One or a combination of request parameters are invalid.
  • errors/malformed_request - The given request has been rejected.
  • errors/content_too_large - The request payload is too large.
  • errors/too_many_characters - The provided content exceeds the character limit.
  • errors/unescaped_characters - The request path contains unescaped characters.
  • errors/limit_too_high - Pagination limit too high. See API reference for details.
401 Unauthorized13 types

Credentials are missing, expired, or otherwise invalid.

  • errors/missing_credentials - Some credentials are necessary to perform the request.
  • errors/multiple_sessions - LinkedIn limits multiple sessions on certain Recruiter accounts. Use the cookie connection method.
  • errors/invalid_checkpoint_solution - The checkpoint resolution did not pass successfully. Retry.
  • errors/invalid_proxy_credentials - The provided proxy credentials are invalid.
  • errors/checkpoint_error - The checkpoint does not appear to be resolvable.
  • errors/invalid_credentials - The provided credentials are invalid.
  • errors/expired_credentials - Credentials have expired. Reconnect the account.
  • errors/insufficient_privileges - This resource is out of your API-key scopes.
  • errors/disconnected_account - The account is disconnected from the provider service.
  • errors/disconnected_feature - The service you're trying to reach is disconnected.
  • errors/invalid_credentials_but_valid_account_imap - IMAP/SMTP credentials are invalid but the account is otherwise valid.
  • errors/expired_link - This link has expired. Generate a new one.
  • errors/wrong_account - The provided credentials do not match the correct account.
500 Internal Server Error3 types

Something went wrong on our side or with the upstream provider.

  • errors/unexpected_error - Something went wrong.
  • errors/provider_error - The provider is experiencing operational problems. Retry later.
  • errors/authentication_intent_error - The current authentication intent was killed after failure. Start again from the beginning.
503 Service Unavailable5 types

postpress is temporarily unable to handle the request.

  • errors/no_client_session - No client session is currently running.
  • errors/no_channel - No channel to client session.
  • errors/no_handler - Handler missing for that request.
  • errors/network_down - Network is down on the server side. Retry shortly.
  • errors/service_unavailable - Service temporarily unavailable. Retry later.
504 Gateway Timeout1 types

The upstream provider did not respond in time.

  • errors/request_timeout - Request timed out. Retry, and contact support if it persists.
Updated May 2026