Known Contacts per Line

Use the contact’s status to choose which number to send from.

GET https://api.sendblue.com/api/v2/lines/contact-status

The result uses the same rules as Sendblue’s new-contact limits. Adding a contact to your account does not make it known, and a contact known on one line can still be new on another.

Query Parameters

Parameter	Type	Required	Description
number	string	Yes	Contact phone number (E.164 format).
sendblue_number	string	Yes	Your Sendblue phone number (E.164 format).

Both values must be valid phone numbers, up to 64 characters each. Formatted phone numbers are converted to E.164. Email addresses, repeated values, and extra query parameters are not supported.

The line must belong to your account. Old lines still available during a replacement grace period are also supported.

Example Request

Use your account’s API credentials. URL-encode the phone numbers to preserve the leading +:

curl --get "https://api.sendblue.com/api/v2/lines/contact-status" \
  --data-urlencode "number=+14155550200" \
  --data-urlencode "sendblue_number=+14155550100" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"

You can also use a temporary bearer token. A line-scoped token can query only the lines it allows.

Success Response (200)

{
  "status": "OK",
  "number": "+14155550200",
  "sendblue_number": "+14155550100",
  "classification": "known",
  "known_contact": true,
  "new_contact_lookback_days": 30,
  "sampled_at": "2026-10-06T19:00:00.000Z"
}

Response Fields

Field	Type	Description
status	string	OK
number	string	Contact phone number in E.164 format.
sendblue_number	string	Sendblue phone number in E.164 format.
classification	string	Contact status; see the table below.
known_contact	boolean or null	true for known, false for new, or null when the status is unavailable or does not apply.
new_contact_lookback_days	number or null	Days without activity before a contact counts as new again. null if this limit does not apply or the setting is unavailable.
sampled_at	string	When the status was checked, as an ISO 8601 timestamp in UTC.

The example uses 30 days. Use the returned new_contact_lookback_days value rather than assuming this is the same for every account.

Contact Status

Classification	known_contact	Description
known	true	Recent incoming or outgoing activity was found for this contact on this line and account.
new	false	No activity was found within the returned number of days.
not_applicable	null	These new-contact limits do not apply to the account, including inbound-only and free shared-line plans.
unavailable	null	Sendblue could not check message history or the limit settings. Retry before using the result to choose a line.

null does not mean the contact is new. Check classification before using known_contact.

What Counts as Activity

Incoming messages count as activity. Outgoing messages count once Sendblue accepts them for sending; requests rejected before that point do not count. Only activity between this contact and this line on your account is included.

After the returned number of days without activity, the contact becomes new again. Recent messages may take a short time to appear in the result.

Known contacts do not count toward new-contact usage, but other sending rules and exemptions still apply. A daily limit of zero keeps the line paused, even for known contacts.

Choosing a Sendblue Line

1. Get each line’s remaining capacity from Line Usage and Capacity.
2. Check the contact’s status on the line you want to use.
3. Reuse a line that knows the contact when possible. For a new contact, choose a line with capacity. Set from_number in your send request.
4. Check the send response. Other messages may have used the remaining capacity since your lookup.

The lookup does not reserve capacity or choose a sender for you. GET /api/v2/contacts lists saved contacts; it does not report whether they are known on a line.

Error Responses

HTTP Status	Description
400	Missing, invalid, repeated, or unsupported query parameters.
401	Invalid API credentials or temporary token.
403	Missing authentication or a temporary token that does not allow the requested line.
404	The line does not belong to your account, is no longer available during a replacement, or was deleted or archived.
429	API request rate limit exceeded.
500	Sendblue could not check whether the line belongs to your account. Retry the request.

If the line check succeeds but message history cannot be checked, the response is HTTP 200 with classification: "unavailable" and known_contact: null. Responses use Cache-Control: no-store.

See the API reference for the response schema.