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#
- 1Send the merchant to iResendly
Make a random
code_verifier(43–128 characters) and keep it for this merchant. Send them tohttps://app.iresendly.com/oauth/authorizewithresponse_type=code, yourclient_id, a registeredredirect_uri, a randomstate, andcode_challenge(the verifier's SHA-256, base64url) withcode_challenge_method=S256. - 2The merchant allows it
They sign in if needed and press Allow or Cancel. Either way they come back to your
redirect_uriwith yourstate: check it matches. - 3Swap the code for a key
Within 10 minutes,
POST https://api.iresendly.com/oauth/token. A code works once. - 4Use the key
Call the Email Marketing API with
Authorization: Bearer irm_…. Start withGET /meto see the account.
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=S256curl -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| What | Details |
|---|---|
| Client authentication | HTTP Basic (as above), or client_id and client_secret in the body. Bodies may be form-encoded or JSON. |
scope | Space-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_uri | Must match a registered address exactly, character for character. http://localhost works for testing. |
| Key lifetime | The key doesn't expire. It stops when the merchant disconnects your app, or when you revoke it. There's no refresh token. |
| Connecting again | Sending 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.
| Status | error | Means |
|---|---|---|
| 400 | invalid_grant | The code is wrong, expired, already used, issued to another app, or the redirect_uri or code_verifier doesn't match. |
| 400 | unsupported_grant_type | Only authorization_code is supported. |
| 401 | invalid_client | Unknown client id, wrong secret, or your app is suspended. |
| 429 | slow_down | Too 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.