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

Connect an account (native authentication)

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

Link to your postpress workspace an account of the given type and provider. The parameters required to perform the authentication depend on the provider you are trying to connect.

Authorization

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

Request body

The request body is one of the variants below, picked by the provider field. All variants share the same proxy and sync-limit options.

bodyobjectrequired
One of the provider variants below.
body array
LinkedIn - Basic authenticationobject
Authenticate using your LinkedIn username and password.
LinkedIn - Basic authentication object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Omit to disable limits.
sync_limit object
chatsstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
messagesstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
providerstringLINKEDINrequired
proxyobject
Optional proxy to route requests through.
proxy object
protocolstring
httpshttpsocks5
hoststringrequired
portnumberrequired
usernamestring
Optional username for proxy's authentication.
passwordstring
Optional password for proxy's authentication.
user_agentstring
If encountering disconnection issues, enter the exact user agent of the browser on which the account has been connected (e.g. `console.log(navigator.userAgent)`).
recruiter_contract_idstring
The contract that should be used with LinkedIn Recruiter.
usernamestringrequired
Should be either an email address or a phone number.
passwordstringrequired
LinkedIn - Cookie authenticationobject
Authenticate using LinkedIn session cookies.
LinkedIn - Cookie authentication object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Omit to disable limits.
sync_limit object
chatsstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
messagesstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
providerstringLINKEDINrequired
proxyobject
Optional proxy to route requests through.
proxy object
protocolstring
httpshttpsocks5
hoststringrequired
portnumberrequired
usernamestring
Optional username for proxy's authentication.
passwordstring
Optional password for proxy's authentication.
user_agentstring
If encountering disconnection issues, enter the exact user agent of the browser on which the account has been connected (e.g. `console.log(navigator.userAgent)`).
recruiter_contract_idstring
The contract that should be used with LinkedIn Recruiter.
access_tokenstringrequired
LinkedIn access token (cookie value of `li_at`).
premium_tokenstring
LinkedIn Recruiter/Sales Navigator cookie (`li_a`). Optional; reuses an existing session when provided.
WhatsAppobject
Connect a WhatsApp account. Uses QR-code authentication by default.
WhatsApp object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
providerstringWHATSAPPrequired
proxyobject
Optional proxy to route requests through.
proxy object
protocolstring
httpshttpsocks5
hoststringrequired
portnumberrequired
usernamestring
Optional username for proxy's authentication.
passwordstring
Optional password for proxy's authentication.
pairing_phone_numberstring
Phone number to login with phone-code pairing. Format: E.164 digits only (country code + number, e.g. 33600000000). Non-digits are ignored. Returns a code to enter in the WhatsApp app. Omit to receive a QR-code checkpoint instead.
Instagram - Basic authenticationobject
Authenticate using your Instagram username and password.
Instagram - Basic authentication object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Omit to disable limits.
sync_limit object
chatsstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
messagesstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
providerstringINSTAGRAMrequired
proxyobject
Optional proxy to route requests through.
proxy object
protocolstring
httpshttpsocks5
hoststringrequired
portnumberrequired
usernamestring
Optional username for proxy's authentication.
passwordstring
Optional password for proxy's authentication.
user_agentstring
If encountering disconnection issues, enter the exact user agent of the browser on which the account has been connected (e.g. `console.log(navigator.userAgent)`).
usernamestringrequired
Your Instagram username.
passwordstringrequired
Your Instagram password.
Instagram - Cookie authenticationobject
Authenticate using Instagram session cookies.
Instagram - Cookie authentication object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Omit to disable limits.
sync_limit object
chatsstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
messagesstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
providerstringINSTAGRAMrequired
proxyobject
Optional proxy to route requests through.
proxy object
protocolstring
httpshttpsocks5
hoststringrequired
portnumberrequired
usernamestring
Optional username for proxy's authentication.
passwordstring
Optional password for proxy's authentication.
user_agentstring
If encountering disconnection issues, enter the exact user agent of the browser on which the account has been connected (e.g. `console.log(navigator.userAgent)`).
sessionidstringrequired
Instagram session ID (cookie value of `sessionid`).
Messenger - Basic authenticationobject
Authenticate using your Messenger username and password.
Messenger - Basic authentication object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Omit to disable limits.
sync_limit object
chatsstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
messagesstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
providerstringMESSENGERrequired
proxyobject
Optional proxy to route requests through.
proxy object
protocolstring
httpshttpsocks5
hoststringrequired
portnumberrequired
usernamestring
Optional username for proxy's authentication.
passwordstring
Optional password for proxy's authentication.
user_agentstring
If encountering disconnection issues, enter the exact user agent of the browser on which the account has been connected (e.g. `console.log(navigator.userAgent)`).
usernamestringrequired
passwordstringrequired
Messenger - Session authenticationobject
Authenticate using an existing Messenger/Facebook session payload.
Messenger - Session authentication object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Omit to disable limits.
sync_limit object
chatsstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
messagesstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
providerstringMESSENGERrequired
proxyobject
Optional proxy to route requests through.
proxy object
protocolstring
httpshttpsocks5
hoststringrequired
portnumberrequired
usernamestring
Optional username for proxy's authentication.
passwordstring
Optional password for proxy's authentication.
user_agentstring
If encountering disconnection issues, enter the exact user agent of the browser on which the account has been connected (e.g. `console.log(navigator.userAgent)`).
cookiesarray of objectsrequired
Messenger/Facebook cookies from an active session. Include at least `xs`, `c_user`, and `datr`.
cookies array
namestringrequired
Cookie name. Include at least `xs`, `c_user`, and `datr`.
valuestringrequired
Cookie value captured from your browser session.
domainstring
pathstring
secureboolean
httpOnlyboolean
expirationDatenumber
sameSitestring
unspecifiedno_restrictionlaxstrict
headersobject
Optional browser headers from the same authenticated session (recommended: `User-Agent`, `Accept-Language`, `Sec-CH-UA*`).
user_namestring
IMAP / SMTP mailboxobject
Connect a generic mailbox using IMAP and SMTP credentials.
IMAP / SMTP mailbox object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitstringNO_HISTORY_SYNC
Currently only `NO_HISTORY_SYNC` is supported.
providerstringMAILrequired
imap_userstringrequired
smtp_userstringrequired
imap_passwordstringrequired
smtp_passwordstringrequired
imap_hoststringrequired
imap_portnumberrequired
smtp_hoststringrequired
smtp_portnumberrequired
imap_encryptionstringrequired
tlssslstarttlsdefault
Gmail (Google OAuth)object
Connect a Gmail mailbox using Google OAuth tokens you have already obtained.
Gmail (Google OAuth) object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitstringNO_HISTORY_SYNC
providerstringGOOGLE_OAUTHrequired
refresh_tokenstringrequired
access_tokenstringrequired
Telegramobject
Set `provider` to `TELEGRAM` to begin authentication. The response contains a string to be rendered as a QR code and scanned. `password` is required if 2FA is enabled on the account.
Telegram object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitobject
Set a sync limit for chats, messages, or both. Chats limit applies per inbox; messages limit applies per chat. Omit to disable limits.
sync_limit object
chatsstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
messagesstring | number
Either a UTC datetime to start sync from, or a quantity of items (0 = no history).
Example: 2025-12-31T23:59:59.999Z
providerstringTELEGRAMrequired
passwordstring
Optional 2FA password.
Outlookobject
Connect an Outlook mailbox using Microsoft OAuth tokens you have already obtained.
Outlook object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
sync_limitstringNO_HISTORY_SYNC
providerstringOUTLOOKrequired
refresh_tokenstringrequired
access_tokenstringrequired
usernamestringrequired
idstringrequired
X / Twitterobject
Connect an X (Twitter) account using credentials.
X / Twitter object
countrystringlength = 2
An ISO 3166-1 A-2 country code to be set as proxy's location.
ipstring
An IPv4 address to infer proxy's location.
disabled_featuresarray of strings
An array of features that should be disabled for this account.
disabled_features array
valuestring
linkedin_recruiterlinkedin_sales_navigatorlinkedin_organizations_mailboxes
providerstringTWITTERrequired
usernamestringrequired
emailstringrequired
passwordstringrequired

Response 201 Created

On success the response contains the newly created account identifier.

objectstringAccountCreatedrequired
account_idstringlength ≥ 1required
A unique identifier for the new account.

Example request (LinkedIn, basic auth)

{
  "provider": "LINKEDIN",
  "username": "anna@acme.com",
  "password": "********"
}

Example response

{
  "object": "AccountCreated",
  "account_id": "acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR"
}

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_credentials`.
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 by the provider.
  • errors/content_too_large - The request payload is too large for the provider.
  • 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 Unauthorized1 types

Authentication is missing or the supplied credentials were rejected.

  • errors/invalid_credentials - The provided credentials are invalid.
403 Forbidden9 types

Authenticated but the account is restricted or the action is not allowed.

  • errors/account_restricted - The account has been restricted by the provider.
  • errors/account_mismatch - Credentials don't match the requested account.
  • errors/insufficient_permissions - The account lacks the required permissions.
  • errors/session_mismatch - The session does not match the current account.
  • errors/feature_not_subscribed - The required feature is not part of your subscription.
  • errors/subscription_required - A subscription is required to use this feature.
  • errors/unknown_authentication_context - Unknown authentication context.
  • errors/action_required - The provider requires an additional action.
  • errors/resource_access_restricted - Access to this resource is restricted.
407 Proxy Authentication Required1 types

The proxy in use is rejecting the connection.

  • errors/proxy_auth_error - The proxy in use is not working. Please try again.
408 Request Timeout1 types

The provider did not respond in time.

  • errors/request_timeout - Communication with the provider has timed out. Please retry.
409 Conflict2 types

The current task conflicts with another in-flight operation.

  • errors/operation_canceled - The current task was canceled by a subsequent one.
  • errors/already_exists - An equivalent account already exists.
425 Too Early1 types

Another authentication intent is still in progress for this account.

  • errors/auth_in_progress - Cannot start a new intent while another is still in progress.
500 Internal Server Error3 types

Something unexpected went wrong on the server side.

  • errors/unexpected_error - Something went wrong.
  • errors/provider_error - The provider is experiencing operational problems.
  • errors/authentication_intent_error - The current authentication intent was killed after failure. Restart from the beginning.
501 Not Implemented1 types

The requested feature is planned but has not been implemented yet.

  • errors/feature_not_implemented - Requested feature is planned but has not been implemented yet.
502 Bad Gateway1 types

The proxy in use is rejecting the connection or returned an invalid response.

  • errors/proxy_error - The proxy in use is not working. Please try again.
503 Service Unavailable5 types

The service is temporarily unavailable; please retry shortly.

  • 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