API Reference/Accounts/List all accounts

List all accounts

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

Returns a list of the accounts linked to your postpress workspace. Use cursor pagination to walk through the full collection.

Authorization

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

Query parameters

cursorstringoptional
A cursor for pagination purposes. To get the next page of entries make a new request and fill this field with the cursor received in the preceding response. Repeat until all entries have been retrieved.
limitintegeroptional1 to 250defaults to 100
Maximum number of items returned in the response. The value can be set between 1 and 250.

Response 200 OK

The response is an AccountList object. Each item is one Account whose connection_params depend on the provider type. Expand any item below to drill into its full schema.

objectstringAccountListrequired
itemsarrayrequired
items array
MOBILEobject
MOBILE object
objectstringAccountrequired
typestringMOBILErequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
phone_numberstringrequired
sim_serial_numberstringrequired
callobjectrequired
call object
phone_numberstringrequired
sim_serial_numberstringrequired
last_fetched_atstring
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
MAILobject
MAIL object
objectstringAccountrequired
typestringMAILrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
imap_hoststringrequired
imap_portnumberrequired
imap_userstringrequired
imap_encryptionstring
tlssslstarttlsdefault
smtp_hoststringrequired
smtp_portnumberrequired
smtp_userstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
GOOGLE_OAUTHobject
GOOGLE_OAUTH object
objectstringAccountrequired
typestringGOOGLE_OAUTHrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
idstringrequired
usernamestringrequired
calendarobjectrequired
calendar object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
ICLOUDobject
ICLOUD object
objectstringAccountrequired
typestringICLOUDrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
imap_hoststringrequired
imap_portnumberrequired
imap_userstringrequired
imap_encryptionstring
tlssslstarttlsdefault
smtp_hoststringrequired
smtp_portnumberrequired
smtp_userstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
OUTLOOKobject
OUTLOOK object
objectstringAccountrequired
typestringOUTLOOKrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
idstringrequired
usernamestringrequired
calendarobjectrequired
calendar object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
GOOGLE_CALENDARobject
GOOGLE_CALENDAR object
objectstringAccountrequired
typestringGOOGLE_CALENDARrequired
connection_paramsobjectrequired
connection_params object
calendarstringrequired
sync_tokenstring
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
WHATSAPPobject
WHATSAPP object
objectstringAccountrequired
typestringWHATSAPPrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
phone_numberstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
LINKEDINobject
LINKEDIN object
objectstringAccountrequired
typestringLINKEDINrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
publicIdentifierstring
usernamestringrequired
premiumIdstring | nullrequired
premiumContractIdstring | nullrequired
premiumFeaturesarray of strings
premiumFeatures array
(item)string
recruitersales_navigatorpremium
organizationsarray of objectsrequired
organizations array
namestringrequired
messaging_enabledbooleanrequired
organization_urnstringrequired
mailbox_urnstringrequired
proxyobject
proxy object
sourcestringUSERrequired
hoststringrequired
portnumberrequired
protocolstring
httphttpssocks5
usernamestring
passwordstring
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
SLACKobject
SLACK object
objectstringAccountrequired
typestringSLACKrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
urlstringrequired
userstringrequired
user_idstringrequired
teamstringrequired
team_idstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
TWITTERobject
TWITTER object
objectstringAccountrequired
typestringTWITTERrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
EXCHANGEobject
EXCHANGE object
objectstringAccountrequired
typestringEXCHANGErequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
imap_hoststringrequired
imap_portnumberrequired
imap_userstringrequired
imap_encryptionstring
tlssslstarttlsdefault
smtp_hoststringrequired
smtp_portnumberrequired
smtp_userstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
TELEGRAMobject
TELEGRAM object
objectstringAccountrequired
typestringTELEGRAMrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
user_idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
INSTAGRAMobject
INSTAGRAM object
objectstringAccountrequired
typestringINSTAGRAMrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
MESSENGERobject
MESSENGER object
objectstringAccountrequired
typestringMESSENGERrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
cursorstring | nullrequired
Opaque cursor for the next page, or `null` when the end has been reached.

AccountSourceServiceStatus

Possible values for sources[].status:

OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.

Example response

{
  "object": "AccountList",
  "items": [
    {
      "object": "Account",
      "type": "LINKEDIN",
      "id": "acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
      "name": "Anna - Sales",
      "created_at": "2026-04-12T09:14:21.000Z",
      "connection_params": {
        "im": {
          "id": "ACoAAB7n2J0BV5...",
          "publicIdentifier": "anna-doe",
          "username": "anna-doe",
          "premiumId": null,
          "premiumContractId": null,
          "premiumFeatures": ["sales_navigator"],
          "organizations": [
            {
              "name": "Acme Inc.",
              "messaging_enabled": true,
              "organization_urn": "urn:li:organization:12345",
              "mailbox_urn": "urn:li:fsd_messagingThread:abc"
            }
          ]
        }
      },
      "current_signature": "sig_default",
      "signatures": [
        { "title": "Default", "content": "Sent from postpress" }
      ],
      "groups": [],
      "sources": [{ "id": "messaging", "status": "OK" }]
    },
    {
      "object": "Account",
      "type": "GOOGLE_OAUTH",
      "id": "acc_01HXYW9X12RKM7DB80WC4SDQ4N",
      "name": "anna@acme.com",
      "created_at": "2026-04-01T11:02:00.000Z",
      "connection_params": {
        "mail":     { "id": "anna@acme.com", "username": "anna@acme.com" },
        "calendar": { "id": "anna@acme.com", "username": "anna@acme.com" }
      },
      "groups": [],
      "sources": [
        { "id": "mail",     "status": "OK" },
        { "id": "calendar", "status": "OK" }
      ]
    }
  ],
  "cursor": null
}

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 Request10 types

Returned when the request can't be processed because of malformed or invalid input.

  • 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 so large that it has been rejected by 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 - Provider cannot accept such high pagination limit (max 250).
  • errors/invalid_action - This action is invalid.
  • errors/invalid_label - This label is invalid.
401 Unauthorized14 types

Returned when the credentials or session for the account are missing, expired or 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 to avoid this.
  • errors/wrong_account - The provided credentials do not match the correct account.
  • errors/invalid_credentials - The provided credentials are invalid.
  • errors/invalid_proxy_credentials - The provided proxy credentials are invalid.
  • errors/invalid_imap_configuration - The provided IMAP configuration is invalid.
  • errors/invalid_smtp_configuration - The provided SMTP configuration is invalid.
  • errors/invalid_checkpoint_solution - The checkpoint resolution did not pass successfully. Retry.
  • errors/checkpoint_error - The checkpoint does not appear to be resolvable. Contact support if it persists.
  • errors/expired_credentials - Credentials have expired. Reconnect the account.
  • errors/expired_link - This link has expired. Generate a new one.
  • 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.
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