Skip to content

Connect with iResendly

For platforms: let merchants connect their iResendly account with one click instead of pasting a key.

If you build a store platform or an app that many iResendly customers use, add a Connect with iResendly button. The merchant signs in to iResendly, sees what your app will be able to do, and presses Allow. You get an Email Marketing API key (irm_…) for their account, so everything in the Email Marketing API works with it unchanged.

It's standard OAuth 2.0: the authorization code flow with PKCE (S256). Most OAuth libraries work with it as they are.

Getting a client id#

Partner apps are registered by the iResendly team, not self-serve. Contact us with your company, website, logo and the exact return addresses (redirect URIs) your app will use. You get a client id (irc_…) and a client secret (ircs_…). Keep the secret on your server.

The flow#

  1. 1
    Send the merchant to iResendly

    Make a random code_verifier (43–128 characters) and keep it for this merchant. Send them to https://app.iresendly.com/oauth/authorize with response_type=code, your client_id, a registered redirect_uri, a random state, and code_challenge (the verifier's SHA-256, base64url) with code_challenge_method=S256.

  2. 2
    The merchant allows it

    They sign in if needed and press Allow or Cancel. Either way they come back to your redirect_uri with your state: check it matches.

  3. 3
    Swap the code for a key

    Within 10 minutes, POST https://api.iresendly.com/oauth/token. A code works once.

  4. 4
    Use the key

    Call the Email Marketing API with Authorization: Bearer irm_…. Start with GET /me to see the account.

Authorize URL
https://app.iresendly.com/oauth/authorize
  ?response_type=code
  &client_id=irc_8f2c41d0b7e9a35c12d4e6f0
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Firesendly%2Fcallback
  &scope=contacts%3Aread%20contacts%3Awrite%20lists%3Aread%20lists%3Awrite
  &state=4f1c9a7e
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
Token request
curl -X POST 'https://api.iresendly.com/oauth/token' \
  -u 'irc_8f2c41d0b7e9a35c12d4e6f0:ircs_xxxxxxxxx' \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_THE_REDIRECT \
  -d redirect_uri=https://yourapp.com/iresendly/callback \
  -d code_verifier=YOUR_CODE_VERIFIER
WhatDetails
Client authenticationHTTP Basic (as above), or client_id and client_secret in the body. Bodies may be form-encoded or JSON.
scopeSpace-separated, from the permissions your app was registered for: contacts:read, contacts:write, lists:read, lists:write, webhooks:manage, events:write. Leave it out to ask for all of them.
redirect_uriMust match a registered address exactly, character for character. http://localhost works for testing.
Key lifetimeThe key doesn't expire. It stops when the merchant disconnects your app, or when you revoke it. There's no refresh token.
Connecting againSending the same merchant through again gives you a new key and ends the old one.

Errors#

Problems with the request come back to your redirect_uri as error (invalid_request, invalid_scope, unsupported_response_type, or access_denied when the merchant cancels) with your state. An unknown client_id or an unregistered redirect_uri is shown on iResendly's page instead and never redirected.

StatuserrorMeans
400invalid_grantThe code is wrong, expired, already used, issued to another app, or the redirect_uri or code_verifier doesn't match.
400unsupported_grant_typeOnly authorization_code is supported.
401invalid_clientUnknown client id, wrong secret, or your app is suspended.
429slow_downToo many requests; try again in a minute.

Disconnecting#

Merchants see your app under Settings → API keys → Connected apps and can disconnect it there. To disconnect from your side, POST https://api.iresendly.com/oauth/revoke with token=irm_… and your client credentials; it always answers 200.

  • The key stops working at once.
  • Webhook endpoints your app added with that connection are removed.
  • Lists your app synced stay in the account, and the merchant can edit them again. If you reconnect and send the same list key, the list is synced again.

The button#

Label it Connect with iResendly. Use your own button style; there's no required artwork.

Still stuck? Write to us and we'll reply by email.Contact ussupport@iresendly.com