This guide explains how to test your API calls to Sender's REST API, verify authentication, validate request and response patterns, and confirm that your integration works correctly before deploying to production.
Prerequisites
- An active Sender account
- An API access token generated from Account settings → API access tokens
- A tool or environment for making HTTP requests (e.g., cURL, Postman, or application code)
- Familiarity with reading JSON response bodies and HTTP status codes
Authentication
All requests to the Sender API require a Bearer token passed in the Authorization header. The base URL for all API v2 endpoints is https://api.sender.net/v2/. Every request must also include Content-Type: application/json and Accept: application/json headers.
A minimal authenticated request looks like this:
bash
curl -X GET \
"https://api.sender.net/v2/subscribers" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
Replace YOUR_API_TOKEN with the token you generated from Account settings → API access tokens. If the token is valid, you receive a 200 response with data. If it is invalid or missing, you receive a 401 response.
Steps to Test API Calls
Step 1 — Verify your authentication with a read-only request
Start by sending a GET request to https://api.sender.net/v2/subscribers to confirm your API token works. This is a safe, read-only call that returns your subscriber list without modifying any data.
bash
curl -X GET \
"https://api.sender.net/v2/subscribers" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
A successful 200 response returns a JSON body with data, links, and meta objects. If you receive a 401 status code, your token is invalid — generate a new one from Account settings → API access tokens.
Step 2 — Test a GET request with query parameters
Send a GET request to https://api.sender.net/v2/groups to retrieve your subscriber groups. Add pagination parameters to test parameterized requests. Append ?page=1&limit=5 to the URL to return only the first five results.
bash
curl -X GET \
"https://api.sender.net/v2/groups?page=1&limit=5" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
The 200 response includes a data array of group objects and a meta object showing current_page, per_page, total, and last_page values. Verify these pagination fields reflect your parameters.
Step 3 — Test a POST request with a request body
Send a POST request to https://api.sender.net/v2/subscribers to test creating a resource. Include a JSON request body with at least the required email field. Set trigger_automation to false to prevent triggering any automations during testing.
bash
curl -X POST \
"https://api.sender.net/v2/subscribers" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"email": "[email protected]",
"firstname": "Test",
"lastname": "User",
"trigger_automation": false
}'
A successful response returns a 200 status with "success": true and the full subscriber object in the data field. If the email field is missing or invalid, the API returns a 422 status with an errors object detailing the validation failure.
Step 4 — Test error handling by sending an invalid request
Intentionally send a malformed request to verify your code handles errors correctly. Send a POST request to https://api.sender.net/v2/subscribers with an invalid email value or omit the required email field entirely.
bash
curl -X POST \
"https://api.sender.net/v2/subscribers" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"email": "not-a-valid-email"}'
The API returns a 422 status code with a response body containing a message field and an errors object. Each key in errors is a field name, and its value is an array of validation messages. Confirm your code parses this structure correctly.
Step 5 — Verify the result in the Sender dashboard
After a successful POST test, confirm the data persists by retrieving it with a GET request. Send a GET request to https://api.sender.net/v2/subscribers/{email} replacing {email} with the email address you used in Step 3.
bash
curl -X GET \
"https://api.sender.net/v2/subscribers/[email protected]" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
The 200 response returns the subscriber's full profile in the data object, including id, email, firstname, lastname, status, and subscriber_tags. You can also log in to the Sender dashboard, navigate to Subscribers, and confirm the test subscriber appears there.
Endpoint Reference
GET /v2/subscribers — Returns a paginated list of all subscribers in your account. Supports page, limit, order, and direction query parameters. No request body required.
GET /v2/subscribers/{email}or{phone}or{ID} — Returns a single subscriber's full profile. Replace the path parameter with the subscriber's email address, phone number, or subscriber ID. No request body required.
POST /v2/subscribers — Creates a new subscriber. The email field is required in the request body. Optional fields include firstname, lastname, groups, fields, phone, and trigger_automation.
GET /v2/groups — Returns a paginated list of all subscriber groups. Supports page, limit, order, and direction query parameters. No request body required.
Error Handling
401 — Unauthorized — The API could not authenticate your request. Verify that your Authorization header uses the format Bearer YOUR_API_TOKEN and that the token is active in Account settings → API access tokens.
400 — Bad request — The request is malformed or references an invalid action. The response body includes a message field with details. Check that your request URL and HTTP method are correct.
404 — Not found — The requested resource does not exist. Verify the endpoint path and any resource IDs or email addresses in the URL are correct.
422 — Bad request parameters — One or more fields failed validation. The response includes a message field and an errors object where each key is a field name mapped to an array of error messages. Fix the invalid fields and retry.
429 — Too many requests — You have exceeded the API rate limit. The response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers. Wait for the number of seconds specified in Retry-After before sending another request.
5xx — Server error — An internal error occurred on Sender's servers. Retry the request after a short delay. If the issue persists, contact [email protected].
API Tips
Use read-only endpoints first — Start testing with GET requests like GET /v2/subscribers or GET /v2/groups to verify authentication and connectivity without modifying any data.
Disable automations during testing — When creating subscribers via the API during testing, set "trigger_automation": false in the request body to prevent unintended automation triggers.
Check response headers for rate limits — Every API response includes X-RateLimit-Remaining and X-RateLimit-Limit headers. Monitor these during testing to understand your usage and implement backoff strategies before hitting limits.
Test pagination with small limits — Use ?page=1&limit=2 to return minimal data while verifying that your pagination logic correctly reads the meta object fields like current_page, last_page, and total.
Log full responses during development — Capture the complete HTTP status code, response headers, and body during testing. This gives you full visibility into errors, rate limit state, and response structure before writing production error handling.
Common Issues
401 on every request → The API token may be expired, revoked, or incorrectly formatted. Ensure the Authorization header value is exactly Bearer YOUR_API_TOKEN with a single space after Bearer. Regenerate the token from Account settings → API access tokens if needed.
422 when creating a subscriber → The email field is either missing or contains an invalid value. Verify the request body is valid JSON with "email" set to a properly formatted email address.
Empty data array in response → The account has no resources of the requested type, or the pagination parameters point beyond the available results. Check the meta.total value and adjust your page parameter.
Connection refused or timeout → The API only accepts HTTPS connections at https://api.sender.net/v2/. Ensure you are not using http:// and that your network allows outbound HTTPS traffic on port 443.
Response body is not JSON → The Accept: application/json header may be missing from your request. Include both Content-Type: application/json and Accept: application/json in every request.
FAQs
Where do I find my API access token? Go to Account settings → API access tokens in the Sender dashboard. Click Create API token to generate a new one. Copy the token immediately — it may not be displayed again after you navigate away.
What is the base URL for all API requests? All Sender API v2 requests use the base URL https://api.sender.net/v2/. Append the specific endpoint path after this base URL. The API is served only over HTTPS.
What tools can I use to test API calls? You can use cURL from the command line, Postman as a graphical client, or write test scripts in any language that supports HTTP requests (JavaScript, Python, PHP, etc.). The Sender API docs provide code examples in JavaScript, PHP, Python, and Bash.
How do I know if my API call was successful? Successful responses return a 200 or 201 status code with the resource data in the response body. Error responses return 4xx or 5xx status codes with a message field and, for validation errors, an errors object describing each invalid field.
What happens if I exceed the API rate limit? The API returns a 429 Too Many Requests response with a Retry-After header. Wait for the specified number of seconds before retrying. Implement exponential backoff in your code to handle rate limits gracefully.
Can I test write operations without affecting my live data? Use the trigger_automation parameter set to false when creating subscribers to prevent automations from firing. You can delete test subscribers after testing. There is no sandbox environment, so all API calls operate on your live account data.
